Metadata-Version: 2.4
Name: wickra-copilot
Version: 0.1.0
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
Requires-Dist: pytest>=7 ; extra == 'test'
Provides-Extra: test
License-File: LICENSE-APACHE
License-File: LICENSE-MIT
Summary: The deterministic market-context core: build a Copilot from a spec, drive it with commands, read back a ranked list of hard facts.
Keywords: trading,llm,copilot,microstructure,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-copilot
Project-URL: Issues, https://github.com/wickra-lib/wickra-copilot/issues
Project-URL: Repository, https://github.com/wickra-lib/wickra-copilot

<p align="center">
  <a href="https://wickra.org"><img src="https://raw.githubusercontent.com/wickra-lib/.github/main/profile/wickra-banner.webp?v=514" alt="Wickra Copilot — a local market copilot grounded in real order book, liquidation and funding microstructure" 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-copilot)
[![CI](https://raw.githubusercontent.com/wickra-lib/.github/main/profile/badges/wickra-copilot/ci.svg)](https://github.com/wickra-lib/wickra-copilot/actions/workflows/ci.yml)
[![CodeQL](https://raw.githubusercontent.com/wickra-lib/.github/main/profile/badges/wickra-copilot/codeql.svg)](https://github.com/wickra-lib/wickra-copilot/actions/workflows/codeql.yml)
[![codecov](https://raw.githubusercontent.com/wickra-lib/.github/main/profile/badges/wickra-copilot/codecov.svg)](https://codecov.io/gh/wickra-lib/wickra-copilot)
[![GitHub release](https://raw.githubusercontent.com/wickra-lib/.github/main/profile/badges/wickra-copilot/release.svg)](https://github.com/wickra-lib/wickra-copilot/releases/latest)
[![crates.io](https://raw.githubusercontent.com/wickra-lib/.github/main/profile/badges/wickra-copilot/crates.svg)](https://crates.io/crates/wickra-copilot)
[![PyPI](https://raw.githubusercontent.com/wickra-lib/.github/main/profile/badges/wickra-copilot/pypi.svg)](https://pypi.org/project/wickra-copilot/)
[![npm](https://raw.githubusercontent.com/wickra-lib/.github/main/profile/badges/wickra-copilot/npm.svg)](https://www.npmjs.com/package/wickra-copilot)
[![NuGet](https://raw.githubusercontent.com/wickra-lib/.github/main/profile/badges/wickra-copilot/nuget.svg)](https://www.nuget.org/packages/Wickra.Copilot)
[![Maven Central](https://raw.githubusercontent.com/wickra-lib/.github/main/profile/badges/wickra-copilot/maven.svg)](https://central.sonatype.com/artifact/org.wickra/wickra-copilot)
[![Go module](https://raw.githubusercontent.com/wickra-lib/.github/main/profile/badges/wickra-copilot/go.svg)](https://pkg.go.dev/github.com/wickra-lib/wickra-copilot-go)
[![R-universe](https://raw.githubusercontent.com/wickra-lib/.github/main/profile/badges/wickra-copilot/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-copilot/license.svg)](#license)
[![OpenSSF Scorecard](https://raw.githubusercontent.com/wickra-lib/.github/main/profile/badges/wickra-copilot/scorecard.svg)](https://scorecard.dev/viewer/?uri=github.com/wickra-lib/wickra-copilot)
[![OpenSSF Best Practices](https://raw.githubusercontent.com/wickra-lib/.github/main/profile/badges/wickra-copilot/best-practices.svg)](https://www.bestpractices.dev)
[![Build provenance](https://raw.githubusercontent.com/wickra-lib/.github/main/profile/badges/wickra-copilot/provenance.svg)](https://github.com/wickra-lib/wickra-copilot/attestations)
[![Docs](https://raw.githubusercontent.com/wickra-lib/.github/main/profile/badges/wickra-copilot/docs.svg)](https://copilot.wickra.org)
[![Verified across 10 languages](https://raw.githubusercontent.com/wickra-lib/.github/main/profile/badges/wickra-copilot/verified.svg)](golden/)
[![Live demo](https://img.shields.io/badge/live%20demo-live.wickra.org-3b82f6)](https://live.wickra.org)

---

# Wickra Copilot

**A local market copilot: an LLM grounded in real order book, liquidation and funding microstructure — the trading assistant that cannot hallucinate the facts.**

> **▶ Live demo:** all 514 indicators over real Binance market data, computed live in your browser — **[live.wickra.org](https://live.wickra.org)** · zero backend, powered by `wickra-wasm`.

> **Part of the [Wickra ecosystem](https://github.com/wickra-lib):** 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

Early development (0.1.0). 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); 0.1.0 is the first
published release. 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.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](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 514 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 514-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 514 O(1) streaming indicators
- [**wickra-genome**](https://github.com/wickra-lib/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**](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

Dual-licensed under either [MIT](LICENSE-MIT) or [Apache-2.0](LICENSE-APACHE), at
your option.

## 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>

