quant-swarm

quant-swarm

Risk-first pre-trade checks that gate live capital — point-in-time data, invariant and leakage audits, regime probes — plus the Shadow Tournament: score your strategy genome against a live, self-evolving trading swarm's champion on identical market paths.

Built by a Principal Quantitative Technologist

Authored by the Principal Quantitative Technologist at The 1.21 Initiative — the same code path that gates live promotion and execution decisions in the trading swarm. Every tool exists because production trading systems fail in two repeatable ways: lookahead leakage in research and an oversized position in production. quant-swarm ships the checkers that prevent both, so you can audit your own work with the exact logic that guards deployed capital.

Your backtest is static. The swarm is not.

Behind this package is a swarm that does not hand-tune strategies. A champion genome runs live; every cycle the swarm breeds challengers (tier-capped mutations), replays champion and challenger on the *identical* episode-seed matrix across five labelled market regimes (high-vol, drawdown, chop, melt-up, gap-heavy), and records the paired outcome in an ELO ledger. A surrogate prior pre-scores candidates so expensive replays are spent where they matter. Nothing is promoted on a single good backtest: promotion requires MIN_EPISODES=20 paired episodes, a Wilcoxon-significant delta, a positive worst-regime margin (maximin, not mean), a deflated-Sharpe margin against the monotonic count of every trial ever attempted, and a PBO cap. This is the champion/challenger, self-play-style loop popularised by AlphaZero-style systems, applied honestly to markets — with the two things that do *not* transfer stated plainly: the market does not react to us, so there is no true self-play, and there is no learned dynamics model or tree search; selection is done by paired replay, ELO and statistical gates.

Replay is only half of it. Every Sunday the swarm also runs a forward league: each league genome — the champion, the top-ELO challengers, contributed genomes, and a *planner* entrant whose weekend moves are chosen by a learned model — seals its positions for the coming week from Friday's causal features, and the SHA-256 commitment is stored before the week happens. The next cycle marks every sealed position against the realised closes (net of each genome's own cost model), ranks the field on the identical real week, and updates ELO on that. Sealed forecasts cannot be overfit to the week that follows; that is the swarm's ground truth, and it feeds a replay buffer where every position is decomposed into its component moves (screen, entry, size, weekend) so credit is assigned per move and regime, not to the strategy as a blob. Forward-league status (as of 2026-10-31): the initial 8-week live-paper collection window started on 2026-09-14 and is currently in Week 7 of 8 (0 weeks settled yet; first batch settlement closes after the 8-week horizon on 2026-11-09).

What that means for you: a local backtest tells you how a strategy did on one path. The Shadow Tournament tells you whether it beats an *evolving* champion on the same paths, in the regime that hurts it most, at a sample size that can actually have an opinion — and your result enters the swarm's ELO ledger. Opt in as a contributor and your genome becomes an external challenger in the swarm's next breeding cycle (at half price), scored in replay and, if it earns a league seat, on real weeks. That is the flywheel: every honest submission makes the champion harder to beat, and every user gets a harder benchmark.

Why risk-first

Risk gates are not post-hoc reports — they are the pre-condition for every action. The package is organized around that constraint:

• Fail-closed by default. Unknown features map to tier C, missing provenance returns UNSCORABLE (never neutral-filled), and unverifiable tokens are refused on the hosted path. See warden.audit_features and features.build provenance guards.
• Pinned, non-drifting invariants. Order sizing floors (per-name 25%, gross 60%), fill model (spread + slippage + adverse selection, both legs, always against you), and hard-constraint checks are vendored at pinned commit SHAs (.github/pins.json, verified byte-for-byte by CI). A parity test pins the three copies of the floors (Python/MCP, C# live engine, Terraform) so they cannot drift.
• Point-in-time provenance. SQLite WAL cache at %LOCALAPPDATA%\1.21-initiative\swarm-mcp\cache.db ($XDG_CACHE_HOME/1.21-initiative/swarm-mcp on POSIX): finalized sessions are never re-fetched, in-progress sessions refresh at most every 60 s, earnings/news are append-only on fetched_at, and features.build runs the no-lookahead guard on every row (each feature must equal a fresh causal recomputation at as_of).
• Pessimistic execution. warden.cost_check and the simulator model the fill that hurts you; there is no optimistic fill path to inflate backtests.
• No order-placement code path. No tool can place, cancel, or route an order — this repository cannot trade, only refuse unsafe trades.
• Statistically honest refusals. Promotion verdicts are never issued locally. Statistically undecidable outputs return INDETERMINATE_LOCAL/UNDERPOWERED/UNSCORABLE, name the exact missing inputs (MIN_EPISODES=20, PBO, DSR, worst-regime margins), and hand off to the hosted Shadow Tournament (tournament.submit).

• Local-first, BYO-key: your Alpaca/AltData keys are read from env only when operating in BYOK mode; otherwise data flows through the hosted relay.
• Explicit Per-Operation Data-Flow Matrix (no blanket claims):
• **Strictly local stdio tools (audit.preflight, audit.quote(mode="local"), audit.run(mode="local"), audit.status, audit.report, audit.compare, warden.*, gym.* on local/cached bars, market.* with caller-supplied bars):** 0 bytes of strategy returns, trades, orders, features, or bars leave your machine. Only SWARM_MCP_ACCESS_TOKEN (when set without SWARM_MCP_LOCAL_TOKEN) is verified once per 5 minutes against POST /api/mcp/verify.
• Relay-backed data tools over stdio (`market.pulse`, `market.sentiment`, `market.regime`, `market.screen`, `market.rank`, `market.flow`, `market.fundamentals_pit`, `market.macro_nowcast`, `market.transfer_entropy`, `market.microstructure`, `volume.forecast`, `pit.analysis`, `cache.warm`): send the requested symbols, as_of / lookback_days, and bearer token to https://1.21initiative.com/api/mcp/* (or Open-Meteo for market.climate coordinates).
• Hosted Audit & Shadow Tournament submissions (`audit.run(mode="hosted")`, `tournament.submit`): send only the explicitly quoted and approved payload. For tournament.submit, this is the genome parameter vector, its genome_hash, the contribute flag, and — on the strategy-contributor tier only — an author-written disclosure and/or strategy_code (treated as inert text, never executed, and deleted after static review).
• **Remote Streamable-HTTP endpoints (https://swarm-mcp-503318750546.europe-west1.run.app/mcp/*):** JSON-RPC tool arguments are transmitted over TLS to the hosted Cloud Run stateless container for execution.

Python vs. C# Evaluator Parity

The live trading swarm's execution risk engine is written in C# (services/risk/Program.cs), while quant-swarm executes in Python (swarm_mcp/vendored/alpha/order_checks.py, swarm_mcp/vendored/guardrails/objective.py, and swarm_mcp/tools/warden_tools.py). Rather than running a local .NET runtime inside the Python wheel, the two implementations are locked together via two mechanisms enforced in CI:

1. Shared Pinned Thresholds (`tests/test_floors_parity.py`): C# environment defaults, Terraform Cloud Run config (cloud_run.tf), vendored guardrails constants (objective.py), and HOUSE_SIZING_FLOORS in warden_tools.py are parsed and asserted equal (MAX_POSITION_PCT = 0.25, MAX_GROSS_EXPOSURE_PCT = 0.60, RISK_PCT_PER_TRADE = 0.008, RISK_ATR_SIZING_MULT = 1.0, OVERNIGHT_GAP_ATR_MULT = 1.2).
2. Numerical Step-by-Step Equivalence Fixtures (`tests/test_sizing_parity.py`, `tests/test_order_checks_parity.py`): warden.explain_sizing and warden.validate_order are parity-tested against hand-computed C# risk-engine fixtures covering integer share floor rounding (floor(equity * 0.008 / (atr * 1.0))), 25% single-position cap trimming, overnight gap > 1.2x ATR halving, and 60% weekend gross-exposure headroom clamping.

One-click install on [Smithery](https://smithery.ai/servers/blink-kt/quant-swarm): the listing is blink-kt/quant-swarm (package and Smithery slug are both quant-swarm); the Smithery stdio launcher starts swarm-data-mcp, and the hosted streamable-HTTP endpoints below serve all three servers. Configuration is optional — without a token the servers still start and list every tool; the first call points you at the free signup. Add a token any time to unlock the relay-backed and hosted tools.

The servers

Flagship Guided Workflow: Quant Swarm Audit (audit.*)

Instead of chaining low-level primitives manually, start every backtest evaluation with the 6-step **audit.*** workflow on swarm-warden-mcp:

1. `audit.preflight` (local, 0 credits) — Pass paths or inline rows for your strategy returns, trade records, benchmark series, execution cost assumptions, and optional feature-provenance manifest (CSV, Parquet, or JSON). Validates timestamps, duplicates, and schema, and returns a Coverage & Scope Matrix separating *Available checks*, *NOT_TESTED checks* (e.g. why returns alone cannot prove absence of lookahead bias in strategy code), and an *Outbound data preview* (0 bytes in local mode).
2. `audit.quote` (0 credits) — Takes preflight_id and returns a deterministic execution plan, runtime estimate, exact credit/GBP cost (£0.00 for mode="local", 20 credits for mode="hosted"), an