<p align="center">
<a href="https://wickra.org"><img src="https://raw.githubusercontent.com/wickra-lib/.github/main/profile/wickra-banner.svg?v=514-8" alt="Wickra Copilot — a local market copilot grounded in real order book, liquidation and funding microstructure" width="100%"></a>
</p>
[](https://github.com/wickra-lib/wickra)
[](https://github.com/wickra-lib/wickra-copilot)
[](https://github.com/wickra-lib/wickra-copilot/actions/workflows/ci.yml)
[](https://github.com/wickra-lib/wickra-copilot/actions/workflows/codeql.yml)
[](https://codecov.io/gh/wickra-lib/wickra-copilot)
[](https://github.com/wickra-lib/wickra-copilot/releases/latest)
[](https://crates.io/crates/wickra-copilot)
[](https://pypi.org/project/wickra-copilot/)
[](https://www.npmjs.com/package/wickra-copilot)
[](https://www.nuget.org/packages/Wickra.Copilot)
[](https://central.sonatype.com/artifact/org.wickra/wickra-copilot)
[](https://pkg.go.dev/github.com/wickra-lib/wickra-copilot-go)
[](https://wickra-lib.r-universe.dev)
[](#license)
[](https://scorecard.dev/viewer/?uri=github.com/wickra-lib/wickra-copilot)
[](https://www.bestpractices.dev)
[](https://github.com/wickra-lib/wickra-copilot/attestations)
[](https://copilot.wickra.org)
[](golden/)
[](https://live.wickra.org)
---
**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](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 Copilot is one data-driven core, [`wickra-copilot-core`](crates/copilot-core): a
serde `ContextSpec` is folded over real microstructure feeds ([`wickra-core`](https://github.com/wickra-lib/wickra)
+ [`wickra-exchange`](https://github.com/wickra-lib/wickra-exchange)) into a
`MarketContext` — 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 `MarketContext` fact 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`](crates/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.
```bash
# 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](ROADMAP.md).
## Documentation
- [Architecture](ARCHITECTURE.md) — the deterministic core, the fact boundary, the LLM adapter, the binding surface.
- Fact & spec reference, the grounding rationale, and per-binding quickstarts under [`docs/`](docs); one runnable example per language under [`examples/`](examples).
- [ROADMAP.md](ROADMAP.md) · [BENCHMARKS.md](BENCHMARKS.md) · [THREAT_MODEL.md](THREAT_MODEL.md) · [SECURITY.md](SECURITY.md).
## Quickstart
```bash
# 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.
```json
{
"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 }`; `value` is
signed, `magnitude` is its ranking key, and `human` is a ready-made sentence
(e.g. `"BTCUSDT dropped -6.44% over the last 20 bars."`). The context is
`MarketContext { 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`](crates/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`, with `WICKRA_COPILOT_BASE_URL` / `_MODEL` overrides).
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](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:
```python
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/`](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
```bash
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](#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 (`facts` is
an alias of `build_context`; `query` answers the same against a stored and
an inline context). The golden fixtures in `golden/` 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++ 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 facts it prints; `examples/ask` compiles 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 `ask` path 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](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 495 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-shazam**](https://github.com/wickra-lib/wickra-shazam) — match an asset's current microstructure fingerprint against its entire history
- [**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 495-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 495 O(1) streaming indicators
- [**wickra-genome**](https://github.com/wickra-lib/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**](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 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.
---
<p align="center">
<a href="https://github.com/wickra-lib/wickra-copilot">
<img alt="GitHub stars" src="https://raw.githubusercontent.com/wickra-lib/.github/main/profile/badges/wickra-copilot/stars.svg">
</a>
<a href="https://github.com/wickra-lib/wickra-copilot/network/members">
<img alt="GitHub forks" src="https://raw.githubusercontent.com/wickra-lib/.github/main/profile/badges/wickra-copilot/forks.svg">
</a>
<a href="https://github.com/wickra-lib/wickra-copilot/issues">
<img alt="GitHub issues" src="https://raw.githubusercontent.com/wickra-lib/.github/main/profile/badges/wickra-copilot/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-copilot star history" width="640"
src="https://raw.githubusercontent.com/wickra-lib/.github/main/profile/badges/wickra-copilot/star-history.svg">
</p>