A local market copilot: an LLM grounded in real order book, liquidation and funding microstructure — the trading assistant that cannot hallucinate the facts.
▶ 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 Copilot is one data-driven core, wickra-copilot-core: a
serde ContextSpec is folded over real microstructure feeds (wickra-core
wickra-exchange) into aMarketContext— a list of hard, numeric facts: price moves, order-book imbalance, liquidation clusters, funding flips, open-interest changes and volatility spikes. Each fact carries its own one-line human sentence. That context is the grounding you hand to an LLM: ask "Why did BTC just dump?" and the answer is anchored to the real order book, liquidations and funding — not vibes.
Because the context is data, not code, the exact same MarketContext crosses
the C ABI and WASM unchanged — and stays byte-for-byte identical between the
parallel (rayon) and sequential (the WASM fallback) builds. The core is exposed
as a JSON-over-C-ABI data API (Copilot::command) in Rust, Python,
Node.js, WASM, C, C++, C#, Go, Java and R, with a reference CLI.
- Deterministic core — the
MarketContextfact list is the only golden-tested surface; it is identical across all ten languages and both build profiles. - Separate LLM adapter — the network call lives in a distinct crate
(
wickra-copilot-llm); it never crosses the C ABI. The deterministic core has no network, no key, no I/O. - Local tool, your own key — not a hosted service and not a SaaS. It runs locally and calls an LLM endpoint with your API key, read from the environment. Ollama runs fully offline; OpenAI / Claude / Gemini use your own key over their endpoints. No vendor lock-in.
- Read-only — it reads market data and asks questions; it never places orders.
# Build the market context from a spec + a per-symbol feed directory,
# and print its derived facts (the same bytes every binding returns):
cargo run -p wickra-copilot -- context --spec golden/specs/dump.json --feeds golden/feeds --format json
# Human-readable list of facts:
cargo run -p wickra-copilot -- context --spec golden/specs/dump.json --feeds golden/feeds
Status
0.2.1 — the current release. The deterministic core, the separate LLM adapter, 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 deterministic core, the fact boundary, the LLM adapter, the binding surface.
- Fact & spec reference, the grounding rationale, and per-binding quickstarts under
docs/; one runnable example per language underexamples/. - ROADMAP.md · BENCHMARKS.md · THREAT_MODEL.md · SECURITY.md.
Quickstart
# Build the market context from a spec + a per-symbol feed directory,
# and print its derived facts (the same bytes every binding returns):
cargo run -p wickra-copilot -- context --spec golden/specs/dump.json --feeds golden/feeds --format json
# Human-readable list of facts:
cargo run -p wickra-copilot -- context --spec golden/specs/dump.json --feeds golden/feeds
# Build the context and ask a local LLM to explain it (Ollama, no API key):
cargo run -p wickra-copilot -- ask --spec golden/specs/dump.json --feeds golden/feeds \
--question "Why did BTC just dump?" --provider ollama
--spec is a ContextSpec; feeds are read either from --feeds <dir> (one
<SYMBOL>.json FeedSnapshot per symbol) or as one JSON object from --stdin.
The context subcommand is fully deterministic and offline; ask adds the LLM
adapter on top.
ContextSpec / facts
A spec is a JSON (or TOML) document: the symbols to inspect, a lookback
window in bars, an optional timeframe, and the facts to derive. The builder
walks each symbol's feed, derives the requested facts, rounds every magnitude to
1e-8, and returns them sorted by magnitude (descending), then kind, symbol and
timestamp (ascending) — a total order, so the output is stable everywhere.
{
"symbols": ["BTCUSDT"],
"lookback": 20,
"timeframe": "1m",
"facts": ["price_move", "orderbook_imbalance", "liquidation_cluster", "funding_flip", "oi_change", "volatility_spike"]
}
- Fact kinds:
price_move,orderbook_imbalance,liquidation_cluster,funding_flip,oi_change,volatility_spike. - Fact —
Fact { kind, symbol, value, magnitude, ts, human };valueis signed,magnitudeis its ranking key, andhumanis a ready-made sentence (e.g."BTCUSDT dropped -6.44% over the last 20 bars."). The context isMarketContext { facts, symbols, lookback }, so it explains itself before any LLM sees it.
Grounding, and why it is deterministic
The MarketContext is computed, not generated: it is a pure function of the
spec and the feeds. command drives a Copilot handle — set_spec,
build_context, query, reset, version — and build_context goes through
one shared code path whether facts are derived in parallel (rayon) or
sequentially. Facts sort by a total order (f64::total_cmp on magnitude, never a
partial float compare), so the JSON is byte-identical across all ten
languages and both build profiles. The LLM can be wrong about interpretation,
but it can never invent the numbers — they are pinned by the golden corpus.
LLM adapter — choose your provider, keep your key
The network call is a separate, swappable crate, wickra-copilot-llm,
consumed by the CLI's ask subcommand. It ships four provider presets plus a
custom one:
- Ollama (default) — fully local, no API key.
- OpenAI, Claude, Gemini — your own key, read from the environment
(
WICKRA_COPILOT_API_KEY, withWICKRA_COPILOT_BASE_URL/_MODELoverrides).
The adapter is read-only and never crosses the C ABI: language bindings surface only the deterministic core. There is no SaaS, no telemetry, and your key stays on your machine. See docs/LLM_ADAPTER.md.
Use in any language
The same Copilot handle — construct from a JSON spec, drive with
command(json) -> json, read version — is reachable from every binding:
import json
from wickra_copilot import Copilot
spec = json.dumps({"symbols": ["BTCUSDT"], "lookback": 3, "facts": ["price_move"]})
feeds = {"BTCUSDT": {"symbol": "BTCUSDT", "candles": [
{"ts": 1, "open": 100, "high": 100, "low": 100, "close": 100, "volume": 1},
{"ts": 2, "open": 97, "high": 97, "low": 97, "close": 97, "volume": 1},
{"ts": 3, "open": 94, "high": 94, "low": 94, "close": 94, "volume": 1}]}}
copilot = Copilot(spec)
context = json.loads(copilot.command(json.dumps({"cmd": "build_context", "feeds": feeds})))
# context is a JSON MarketContext: {"facts":[{"kind":"price_move","symbol":"BTCUSDT",...}],...}
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/copilot-core the deterministic core (ContextSpec, facts, MarketContext, command_json)
crates/copilot-llm the separate LLM adapter (providers, prompt) — never crosses the C ABI
crates/copilot-cli the CLI (bin: wickra-copilot; context + ask subcommands)
crates/copilot-bench criterion benchmarks
bindings/{python,node,wasm,c,go,csharp,java,r} the ten-language surface
golden/ a deterministic feed universe, specs, and byte-exact expected contexts
fuzz/ cargo-fuzz targets (spec_parse, feed_parse, build_context, query)
examples/ one runnable "build a context" example per language, plus examples/ask (LLM demo)
Building everything from source
cargo build --workspace
cargo test --workspace --all-features
cargo test --workspace --no-default-features # sequential build path
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo run -p wickra-copilot -- context --spec golden/specs/dump.json --feeds golden/feeds --format json
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-copilot-core— unit tests per fact derivation, the context fold, the parallel-versus-sequential parity, property tests over the feed universe and the command envelope, and the operating-mode check (factsis an alias ofbuild_context;queryanswers the same against a stored and an inline context). The golden fixtures ingolden/are the anchor: the same(spec, feeds)pair must build the same context bytes here as in every binding.wickra-copilot-llm— offline only: the rendered prompt bytes and the API-key redaction. The model's answer is never part of any test.- 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 facts it prints;examples/askcompiles in CI and runs only locally, since it talks to a model. - Fuzz —
fuzz/holds libFuzzer targets over spec parsing, feed parsing, the command envelope and the query; 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.
- The LLM
askpath additionally needs a reachable provider: a local Ollama server, or an API key for OpenAI / Claude / Gemini.
See each bindings/<lang>/README.md for the per-language build and install.
Benchmarks
crates/copilot-bench measures build_context scaling by universe size and
lookback, 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-shazam — match an asset's current microstructure fingerprint against its entire history
- 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 Copilot is analysis software: it builds a deterministic market context and relays it to a language model of your choosing. It is provided "as is", without warranty of any kind. LLM output can be wrong and is not financial advice; the copilot only reports facts and 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-copilot 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_copilot-0.2.1.tar.gz | 85.0 kB | Without provenance | Details for wickra_copilot-0.2.1.tar.gz |
Built distributions (wheels)
Total release size: 3.2 MB
Release files / wickra_copilot-0.2.1.tar.gz
| Download URL | wickra_copilot-0.2.1.tar.gz |
|---|---|
| Size | 85.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
6f77969c6bcf0dff27d04814845a4c3e7956daadeb66dd28839970428a56f7bc
|
|
BLAKE2b-256 checksum How to use checksums |
03ffa74b8cd6ca9169ef082b846985521ded00cbaf11d8e2ac86c29decbca0c4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
maturin/1.15.0
|
Release files / wickra_copilot-0.2.1-cp39-abi3-win_arm64.whl
| Download URL | wickra_copilot-0.2.1-cp39-abi3-win_arm64.whl |
|---|---|
| Size | 259.3 kB |
| Tags | CPython 3.9 Windows ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
c2f42018e48fa18d271f70aae4ca8357ba62c39bd983bb815d7b4b6da806525f
|
|
BLAKE2b-256 checksum How to use checksums |
828780b054873f837242a85d44036d808725a9fe0922f20a8e8d2a11370f8faa
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
maturin/1.15.0
|
Release files / wickra_copilot-0.2.1-cp39-abi3-win_amd64.whl
| Download URL | wickra_copilot-0.2.1-cp39-abi3-win_amd64.whl |
|---|---|
| Size | 280.0 kB |
| Tags | CPython 3.9 Windows x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
87ff1e730b28bc3f24c19cc0a2fbb450d4014fe4bc13f0b43dd017147d6227a6
|
|
BLAKE2b-256 checksum How to use checksums |
57cd95ba321fdbad3cbf509c25b8e80ab35a5ec9bb11f33e87f8ff8741eaf6d0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
maturin/1.15.0
|
Release files / wickra_copilot-0.2.1-cp39-abi3-musllinux_1_2_x86_64.whl
| Download URL | wickra_copilot-0.2.1-cp39-abi3-musllinux_1_2_x86_64.whl |
|---|---|
| Size | 593.3 kB |
| Tags | CPython 3.9 Linux musl 1.2+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
ee30779419096eaf5feb3102d1e5ff9269dc3dda33a56435fa5337fad390f6c6
|
|
BLAKE2b-256 checksum How to use checksums |
c4d0b5cb1e69f3bd818a4f6288d89222900ffb3564f99e5061361348626057f9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
maturin/1.15.0
|
Release files / wickra_copilot-0.2.1-cp39-abi3-musllinux_1_2_aarch64.whl
| Download URL | wickra_copilot-0.2.1-cp39-abi3-musllinux_1_2_aarch64.whl |
|---|---|
| Size | 533.9 kB |
| Tags | CPython 3.9 Linux musl 1.2+ ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
4eb7acef9ef3a7108f919a163271447e38e9b1c8b3d7cab20e5b650644ec4ebe
|
|
BLAKE2b-256 checksum How to use checksums |
164765ad2c8c92d48a6b03e817af876598e7f40d760451737bcb38930ce470fa
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
maturin/1.15.0
|
Release files / wickra_copilot-0.2.1-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | wickra_copilot-0.2.1-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl |
|---|---|
| Size | 381.4 kB |
| Tags | CPython 3.9 Linux glibc 2.17+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
6e970407b6d66bcd39846226c54db72777b762c3b642d43c0206060675f7aaf9
|
|
BLAKE2b-256 checksum How to use checksums |
584661dd93e0e1043100bc3d15a31507217bc7c0e8a7196247c1d065fad5cc15
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
maturin/1.15.0
|
Release files / wickra_copilot-0.2.1-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | wickra_copilot-0.2.1-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl |
|---|---|
| Size | 355.3 kB |
| Tags | CPython 3.9 Linux glibc 2.17+ ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
e06569315cf75fee33505c1d14b3ae93843e218f617052525275f9b18f841b48
|
|
BLAKE2b-256 checksum How to use checksums |
60129ee58ab8f92760ebe0187f0ba288c55a0baa00155883f835ba8266a6278e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
maturin/1.15.0
|
Release files / wickra_copilot-0.2.1-cp39-abi3-macosx_11_0_arm64.whl
| Download URL | wickra_copilot-0.2.1-cp39-abi3-macosx_11_0_arm64.whl |
|---|---|
| Size | 328.8 kB |
| Tags | CPython 3.9 abi3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
982d2a0319ba42525901a379605708a4f233b6e6e99d3bf14acfcd16297417a3
|
|
BLAKE2b-256 checksum How to use checksums |
1f549af8f58016c2f2a8820077b7169f1409f26dbeb48d31c21e04aa7277ab63
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
maturin/1.15.0
|
Release files / wickra_copilot-0.2.1-cp39-abi3-macosx_10_12_x86_64.whl
| Download URL | wickra_copilot-0.2.1-cp39-abi3-macosx_10_12_x86_64.whl |
|---|---|
| Size | 356.6 kB |
| Tags | CPython 3.9 abi3 macOS 10.12+ x86-64 |
|
SHA-256 checksum How to use checksums |
ad547a6531be06167ad4799b155db1ff54d07be82e8bd005b219899a372fbcf9
|
|
BLAKE2b-256 checksum How to use checksums |
cf6f5397966fd4200d4f14581a44f33f3ed667971882bdbfa9cd7af914767b28
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
maturin/1.15.0
|
Security for wickra-copilot 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.