wickra-copilot 0.1.3

---

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 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); 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.1.3 — 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 under examples/.
• 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 }; 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, 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.

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 (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.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.
• 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.

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 514 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 514-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 514 O(1) streaming indicators
• 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 — 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_std artifact
• wickra-embed — allocation-free, no_std streaming 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.