Skip to main content

Wickra Gym — a Gymnasium-compatible, microstructure-aware backtest environment with O(1) steps for fast, deterministic RL rollouts

CI codecov PyPI License: MIT OR Apache-2.0

Wickra Gym — Python


Part of the Wickra ecosystem — for Python. pip install wickra-gym — prebuilt wheels for Linux, macOS and Windows, nothing to compile.

A deterministic, Gymnasium-compatible backtest environment. The whole candle dataset is precomputed once into a fixed feature tensor, so each step() is a constant-time array index — and the same spec, data, seed and actions produce a byte-identical trajectory across every language binding.

Install

pip install wickra-gym

Pre-built wheels ship for Linux, macOS and Windows — there is nothing to compile and no C library to track down.

Quick start

examples/python/rollout.py is the runnable example the CI smoke job executes; in full:

"""Raw rollout over the native command surface (no Gymnasium required).

    python examples/python/rollout.py

Reads the momentum_discrete spec and its candle dataset, then drives a fixed
long policy through the environment via ``RawEnv.command`` — the same JSON-in /
JSON-out boundary every language binding forwards verbatim, so this trajectory
is byte-identical to the C, Node, Go, C#, Java and R examples on the same seed.
"""

import json
from pathlib import Path

from wickra_gym import RawEnv, __version__

DATA = Path(__file__).resolve().parent.parent / "data"

def main() -> None:
    spec = (DATA / "specs" / "momentum_discrete.json").read_text()
    candles = json.loads((DATA / "candles.json").read_text())

    env = RawEnv(spec)
    env.command(json.dumps({"cmd": "load", "candles": candles}))

    reset = json.loads(env.command(json.dumps({"cmd": "reset", "seed": 42})))
    print(f"wickra-gym {__version__}")
    print("reset observation:", reset["observation"])

    equity = 0.0
    step = 0
    while True:
        result = json.loads(env.command(json.dumps({"cmd": "step", "action": 2})))
        equity += result["reward"]
        print(
            f"step {step}: reward {result['reward']:+.6f}  equity {equity:+.6f}  "
            f"terminated={result['terminated']} truncated={result['truncated']}"
        )
        if result["terminated"] or result["truncated"]:
            break
        step += 1

if __name__ == "__main__":
    main()

Use as a Gymnasium environment

import numpy as np
from wickra_gym import WickraGymEnv

spec = """{
  "dataset_ref": "demo", "symbol": "BTCUSDT",
  "observation": {"features": [
    {"kind": "price", "field": "close"},
    {"kind": "indicator", "name": "Rsi", "params": [14]}
  ]},
  "action_space": {"type": "discrete", "n": 3},
  "reward": "pnl",
  "episode": {"max_steps": 256, "warmup": 14}
}"""

candles = [
    {"ts": i, "open": 100 + i, "high": 100 + i, "low": 100 + i, "close": 100 + i}
    for i in range(300)
]

env = WickraGymEnv(spec, candles)
obs, info = env.reset(seed=0)
done = False
while not done:
    action = env.action_space.sample()
    obs, reward, terminated, truncated, info = env.step(action)
    done = terminated or truncated

The observation and action spaces are derived from the spec: unbounded observation columns use ±np.inf; a discrete action space becomes spaces.Discrete(n) and a continuous one becomes a 1-D spaces.Box.

Register it under a Gymnasium id:

from wickra_gym import register
register()  # WickraGym-v0

The raw command surface

RawEnv is the thin, dependency-free wrapper over the native command JSON surface — the same boundary every language binding forwards verbatim:

import json
from wickra_gym import RawEnv

env = RawEnv(spec)
env.command(json.dumps({"cmd": "load", "candles": candles}))
reset = json.loads(env.command(json.dumps({"cmd": "reset", "seed": 0})))
step = json.loads(env.command(json.dumps({"cmd": "step", "action": 2})))

Commands: load, reset, step, spec, version. Domain errors come back as {"ok": false, "error": ...}; a bad spec raises ValueError at construction.

Benchmark

Every binding forwards to the same data-driven Rust core, so what this one adds is the call overhead of PyO3, not a different result. The core's throughput is measured by the repository's benchmark suite and the nightly bench.yml run; the numbers, the machine and how to reproduce them are in the repository BENCHMARKS.md.

Documentation

The full guide, the spec reference and the API documentation live in the main repository and the documentation site:

Wickra Gym ships native bindings for Python, Node.js, WASM and Rust, plus a C ABI hub that any C-capable language (C, C++, C#, Go, Java, R) links against — all forwarding to the same data-driven, unsafe-forbidden Rust core.

Security

Found a security issue? Please don't open a public issue. Report it privately via the repository's Security tab ("Report a vulnerability") or email support@wickra.org with a subject line starting [wickra security]. Full policy: https://github.com/wickra-lib/wickra-gym/blob/main/SECURITY.md.

Disclaimer

wickra-gym is research and engineering tooling, not financial advice. A trained agent's backtested performance says nothing about future returns; markets carry risk and you are responsible for your own decisions. wickra-gym is free software you run yourself: no hosted service, no data collection, no warranty.

License

Licensed under either of Apache-2.0 or MIT at your option.

Metadata

Release files for wickra-gym 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-gym 0.2.1
File Size Uploaded Provenance Actions
wickra_gym-0.2.1.tar.gz 75.5 kB Without provenance Details for wickra_gym-0.2.1.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for wickra-gym 0.2.1
File Actions
wickra_gym-0.2.1-cp39-abi3-win_arm64.whl CPython 3.9 abi3 Windows ARM64 Details for wickra_gym-0.2.1-cp39-abi3-win_arm64.whl
wickra_gym-0.2.1-cp39-abi3-win_amd64.whl CPython 3.9 abi3 Windows x86-64 Details for wickra_gym-0.2.1-cp39-abi3-win_amd64.whl
wickra_gym-0.2.1-cp39-abi3-musllinux_1_2_x86_64.whl CPython 3.9 abi3 Linux musl 1.2+ x86-64 Details for wickra_gym-0.2.1-cp39-abi3-musllinux_1_2_x86_64.whl
wickra_gym-0.2.1-cp39-abi3-musllinux_1_2_aarch64.whl CPython 3.9 abi3 Linux musl 1.2+ ARM64 Details for wickra_gym-0.2.1-cp39-abi3-musllinux_1_2_aarch64.whl
wickra_gym-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_gym-0.2.1-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
wickra_gym-0.2.1-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl CPython 3.9 abi3 Linux glibc 2.17+ ARM64 Details for wickra_gym-0.2.1-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
wickra_gym-0.2.1-cp39-abi3-macosx_11_0_arm64.whl CPython 3.9 abi3 macOS 11.0+ ARM64 Details for wickra_gym-0.2.1-cp39-abi3-macosx_11_0_arm64.whl
wickra_gym-0.2.1-cp39-abi3-macosx_10_12_x86_64.whl CPython 3.9 abi3 macOS 10.12+ x86-64 Details for wickra_gym-0.2.1-cp39-abi3-macosx_10_12_x86_64.whl

Total release size: 5.5 MB

Release files / wickra_gym-0.2.1.tar.gz

Download URL wickra_gym-0.2.1.tar.gz
Size 75.5 kB
Tags Source
SHA-256 checksum
How to use checksums
1f78fbfd84bdbdf84f8056bfbb08dc9f4addc724a6da33767463ef127d7ff303
BLAKE2b-256 checksum
How to use checksums
bde80f7be46056b6989e7c6edf89751cdc3f3a13cf4eb56779662966480a6130
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.15.0

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

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

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

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

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

Download URL wickra_gym-0.2.1-cp39-abi3-musllinux_1_2_x86_64.whl
Size 926.0 kB
Tags CPython 3.9 Linux musl 1.2+ x86-64 abi3
SHA-256 checksum
How to use checksums
0124c184e1261d39f6adce103a5fd31971926cdd8ff090bb43f2455c9a35f1f8
BLAKE2b-256 checksum
How to use checksums
8c469637bca96a2afaf941854ad758507df537d5ea0689a48af21a55c6324ab0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.15.0

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

Download URL wickra_gym-0.2.1-cp39-abi3-musllinux_1_2_aarch64.whl
Size 815.9 kB
Tags CPython 3.9 Linux musl 1.2+ ARM64 abi3
SHA-256 checksum
How to use checksums
2b8a18946693bb30dc7603fcc4515e159ab33ce79307269113ca924db67fa056
BLAKE2b-256 checksum
How to use checksums
6279a87bce034eccf2a2c125b1705ea202c996152103292dcf2817f6d29dbe54
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.15.0

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

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

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

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

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

Download URL wickra_gym-0.2.1-cp39-abi3-macosx_11_0_arm64.whl
Size 582.1 kB
Tags CPython 3.9 abi3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
1fdbe8c3a6155c7751a0a34b2ca429bdc45bfbafd1014532f05f20ce4733a71d
BLAKE2b-256 checksum
How to use checksums
dce76594f654b04698080115359b280a59b62387f2c149b754c8630a4825ff21
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.15.0

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

Download URL wickra_gym-0.2.1-cp39-abi3-macosx_10_12_x86_64.whl
Size 678.6 kB
Tags CPython 3.9 abi3 macOS 10.12+ x86-64
SHA-256 checksum
How to use checksums
70b77d0a16404864facb20f10990487d22751af570080ee3bf0c110b1c84bbd8
BLAKE2b-256 checksum
How to use checksums
28f77e5588f3490ea3702722cd07ca96279b570d79404cb833c7742bf368a129
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.15.0

Security for wickra-gym 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