ruflo-neural-trader

Neural trading strategies powered by neural-trader (v2.7+) — self-learning LSTM/Transformer/N-BEATS models, Rust/NAPI backtesting (8-19x faster), 112+ MCP tools, swarm coordination, and portfolio optimization.

Overview

Wraps the neural-trader npm package as a Ruflo plugin with 4 specialized agents, 7 skills, and comprehensive CLI commands. Adds AgentDB memory persistence, SONA trajectory learning, and swarm-coordinated execution on top of neural-trader's Rust/NAPI engine.

Heavy jobs — multi-year walk-forward backtests, large Monte-Carlo runs, parameter sweeps, LSTM/Transformer/N-BEATS training — can be dispatched to an Anthropic Managed Agent cloud container instead of running locally: see the trader-cloud-backtest skill, the /trader cloud <backtest|train|sweep> command, and ADR-117 (built on the managed_agent_* runtime from the ruflo-agent plugin / ADR-115; needs ANTHROPIC_API_KEY + Managed Agents beta — degrades to the local trader-backtest skill without it).

Prerequisites

✅ neural-trader@^2.8.11 (shipped 2026-05-14; see post-mortem gist and announcement #1981). Resolves four compounding bugs that made the package unusable since v2.5.0:

1. Install-hook fork-bomb (#1974 — 120 GB RAM on Apple Silicon) — fixed in 2.7.2 (neural-trader#109).
2. require('neural-trader') always threw Cannot find module './src/cli/lib/napi-loader-shared' — missing files restored in 2.7.5 (neural-trader#111).
3. cargo build aborted on aarch64-apple-darwin (fasthash-sys x86-only SIMD) — placeholder hash replaced with stdlib DefaultHasher in 2.7.5.
4. npm tarball claimed 5 platform binaries, shipped 1 — darwin-arm64 + darwin-x64 added in 2.7.6.

The 2.8.x line additionally adds a flag-style CLI dispatcher (--backtest, --signal scan, --risk assess, --portfolio optimize, --regime, --train, --predict, --strategy-create) running real math (SMA crossover / RSI mean-reversion / pairs z-score / adaptive regime-switching / multi-indicator RSI+MACD+Bollinger) against real Yahoo Finance data via --live. Supports --walk-forward, --monte-carlo, --symbols A,B,C, --benchmark SPY, --optimize --param "name:min:max:step". The runtime smoke (scripts/runtime-smoke.sh) covers 20 documented entry points end-to-end (basic commands + Kelly + walk-forward + Monte Carlo + optimize + multi-symbol + pairs + adaptive + multi-indicator).

# Recommended — keeps --ignore-scripts as defense in depth. The install
# hook is safe in 2.7.2+, but --ignore-scripts protects against any
# future install-script regression on this or transitive packages.
npm install --ignore-scripts neural-trader@^2.8.11

🚨 If you must use an older version ([email protected] or below — same fork-bomb risk on every non-linux-x64 host) always pass --ignore-scripts to skip the malicious install hook. The linux-x64 binary is hardcoded inline in the tarball, so on linux-x64 the package still works after --ignore-scripts. On other platforms --ignore-scripts at least won't fork-bomb your machine.

bashCopy

# Only needed for neural-trader <= 2.7.1 — DO NOT run plain `npm install
# neural-trader@<=2.7.1` on macOS / Windows / linux-arm64.
npm install --ignore-scripts neural-trader@<=2.7.1

The audit-neural-trader-safety.mjs CI guard in this repo still enforces --ignore-scripts on every documented invocation — defense in depth in case anyone pins to an older version in a lockfile.

Installation

claude --plugin-dir plugins/ruflo-neural-trader

MCP Integration (112+ Tools)

neural-trader exposes 112+ MCP tools for direct Claude Desktop access:

claude mcp add neural-trader -- npx neural-trader mcp start

Agents

Skills

Commands

# Strategy management
trader strategy create <name> --type <momentum|mean-reversion|pairs|adaptive>
trader backtest <strategy> --symbol <TICKER> --period <range>

# Neural model training
trader train <lstm|transformer|nbeats> --symbol <TICKER>

# Signal generation
trader signal scan [--strategy <name>] [--symbols <TICKERS>]

# Market analysis
trader regime --symbol <TICKER>
trader indicators --symbol <TICKER> --indicators rsi,macd,bollinger
trader correlation --symbols <TICKERS> --window 30d

# Risk & portfolio
trader risk assess [--symbol <TICKER>]
trader portfolio optimize [--risk-target <number>]

# Live trading
trader live --broker <name> [--swarm enabled]

# History
trader history

Neural Models (via neural-trader)

npx neural-trader --model lstm --symbol TSLA --confidence 0.95
npx neural-trader --model transformer --symbol BTC-USD --predict
npx neural-trader --model nbeats --symbol SPY --decompose

Strategy Types

Market Regime Detection

Anomaly Detection

neural-trader Z-score composite scoring on OHLCV: anomalyScore = min(1, meanZ / 3)

Circuit Breakers

Backtesting Features

Performance

neural-trader uses Rust/NAPI bindings for zero-overhead performance:

• 8-19x faster than Python equivalents
• Sub-200ms order execution and risk checks
• WASM/SIMD acceleration available
• 52,000+ inserts/sec for market data

Compatibility

• CLI: pinned to @claude-flow/cli v3.6 major+minor.
• Runtime: npx neural-trader (Rust/NAPI bindings — 112+ MCP tools).
• Verification: bash plugins/ruflo-neural-trader/scripts/smoke.sh is the contract.

Namespace coordination

This plugin owns five AgentDB namespaces (kebab-case, follows the convention from ruflo-agentdb ADR-0001 §"Namespace convention"). The canonical five-namespace set is defined by ADR-126 Phase 1:

Note: the namespace prefix is trading- (the actual intent) rather than neural-trader- (the plugin stem). This is a deliberate ergonomic choice — trading is the load-bearing concern downstream consumers reason about. Reserved namespaces (pattern, claude-memories, default) MUST NOT be shadowed.

All access via memory_* (namespace-routed). No agentdb_hierarchical-* or agentdb_pattern-store with namespace arguments — the plugin uses the correct routing throughout.

Memory lifecycle (ADR-125 integration)

This plugin relies on @claude-flow/[email protected] for the lifecycle guarantees defined in ADR-125 and wired by ADR-126 Phase 2:

• Warm HNSW restart — @claude-flow/[email protected] (ADR-125 Phase 3) snapshots the HNSW index to a .hnsw sidecar file, so neural-trader process restarts no longer rebuild the strategy / regime similarity index from scratch. No plugin-side change is required to benefit; routing is automatic through MemoryService.search().
• Hybrid retrieval (RRF + MMR) — market-analyst regime-similarity queries automatically become hybrid (dense ANN + sparse FTS5 keyword, reciprocal-rank-fused and MMR-diversified) via the same MemoryService.search() path (ADR-125 Phase 5). When the embedding generator is unavailable, retrieval gracefully degrades to keyword-only rather than throwing.
• Signal TTL (24h) — trader-signal writes to trading-signals with expiresAt: now + 24h. The MemoryConsolidator.sweepExpired() pass (ADR-125 Phase 4) removes them from all indexes — including HNSW — when they expire. Long-running ruflo sessions no longer accumulate stale intraday signals.
• Backtest dedup — trader-backtest proactively deletes prior entries for the same (strategyId, paramsHash) before storing a fresh one. The same outcome is also produced asynchronously by the MemoryConsolidator.dedup('keep-newest') background pass that runs every 6 hours.
• Consolidator schedule — the consolidator runs every 6 hours by default (sweepExpired + dedup + compactHnsw), and also on MemoryService.close(). No plugin-side wiring is required.

Portfolio CG path (ADR-126 Phase 3 / ADR-123 Wedge 8)

The new trader-portfolio-cg skill solves the mean-variance problem Σ · x = μ via Conjugate Gradient instead of the legacy Neumann series. CG is provably optimal for symmetric positive-definite inputs (covariance matrices are SPD by construction), and the upstream [email protected] benchmark shows ~816 ns CG vs ~50 µs Neumann at n=256 — a measured 40-60× speedup (ADR-123 §162 Row 8).

When it's used: any time the team wants optimal portfolio weights — call /trader-portfolio-cg instead of /trader-portfolio. The skill reads the current covariance and expected-return vector from npx neural-trader --portfolio current --json, dispatches to mcp__ruflo-sublinear__solve (when the ruflo-sublinear plugin is registered), and writes weights with provenance metadata (method: 'cg-sublinear' | 'cg-local' | 'neumann-fallback') to the trading-risk namespace.

How to disable: set RUFLO_NEURAL_TRADER_DISABLE_CG=1 to skip the CG path entirely and fall back to the legacy npx neural-trader --portfolio optimize route. Useful for A/B validation or when an upstream covariance regression breaks SPD.

Parity guarantee: ||cg_solution − neumann_solution||_∞ < 1e-4 on every benchmark seed — verified by benchmarks/portfolio-cg.bench.mjs and asserted by scripts/smoke-neural-trader-portfolio-cg.mjs.

Local fallback: the adapter (src/sublinear-adapter.ts + .mjs mirror) ships a self-contained ~50-LOC CG kernel so the skill works even before the ruflo-sublinear plugin lands on the IPFS registry. The same call site picks up the full native-WASM speedup automatically once mcp__ruflo-sublinear__solve is registered in the runtime.

# Run the bench yourself:
node plugins/ruflo-neural-trader/benchmarks/portfolio-cg.bench.mjs

# Run the contract smoke:
node scripts/smoke-neural-trader-portfolio-cg.mjs

Feature attribution (ADR-126 Phase 6 / ADR-123 single-entry PR)

The new trader-explain skill closes the regulator-grade interpretability gap that LSTM / Transformer trading signals leave by default. Given a signalId, it builds a feature-contribution graph (nodes = features, edges = co-attention weights, source = signal output) and runs single-entry forward-push PageRank to produce a top-K ranked list of the features that most influenced the model's prediction.

When to use it: any time a trading signal needs an audit trail — pre-trade risk review, regulator filings under the EU AI Act (Article 13 — transparency for high-risk AI) or SEC Reg-AI interpretability guidance, post-mortem of a stop-loss event, or input to the risk-analyst before a paper→live promotion. Call /trader-explain <signalId> (or pass --top-k 10 --seed 42 to control ranking depth + reproducibility).

Output: a SignedAttributionArtifact written to the canonical trading-analysis namespace, plus a markdown summary surfaced to the agent. The artifact is Ed25519-signed using the same scheme as Phase 4 backtest artifacts — the verifier pins to a trusted public key (CWE-347 / #1922), so downstream consumers can refuse any tampered or unsigned artifact.

// Schema — plugins/ruflo-neural-trader/src/signed-attribution.ts
interface SignedAttributionArtifact {
  schema: 'ruflo-neural-trader-attribution/v1';
  signalId: string;
  modelId: string;                         // e.g. 'lstm-v3', 'transformer-attn8h-v2'
  features: Array<{
    name: string;                          // e.g. 'rsi_14', 'attention_head_3', 'price_close_t-7'
    score: number;                         // PageRank score in [0, 1]
    rank: number;                          // 1-indexed
  }>;
  graphMetadata: {
    nodeCount: number;
    edgeCount: number;
    pageRankIterations: number;
    seed: number;                          // load-bearing — same seed → same ordering
  };
  generatedAt: string;
  witnessPublicKey: string;
  witnessSignature: string;
}

Example markdown surfaced to the agent:

## Feature attribution for signal `sig-momentum-spy-20260519-001` (model: transformer-attn8h-v2)

| Rank | Feature              | Score |
|------|----------------------|-------|
| 1    | rsi_14               | 0.42  |
| 2    | attention_head_3     | 0.21  |
| 3    | price_close_t-7      | 0.13  |
| 4    | macd_signal          | 0.09  |

- PageRank iterations: 18
- Graph: 17 nodes, 42 edges
- Seed: 42 (reproducible — same seed → same ordering)
- Path: local | mcp
- Signature: ed25519:abcd…

Reproducibility guarantee: two runs with the same signalId + same --seed produce byte-identical rank ordering. Asserted by scripts/smoke-neural-trader-feature-attribution.mjs (the smoke runs the local seeded PageRank twice and compares scores element-wise).

Local fallback: when mcp__ruflo-sublinear__page-rank-entry is not registered in the runtime, the skill falls through to a ~30-LOC seeded power-iteration kernel that ships in src/signed-attribution.mjs. Same math, same ordering for the same seed. The native-WASM path picks up automatically once ruflo-sublinear lands on the IPFS registry.

--explain fallback: if the installed neural-trader build doesn't yet expose --predict --explain --json, the skill degrades to a z-score-magnitude heuristic over the signal's input vector and tags the artifact attribution_method: "input-zscore-fallback" so downstream consumers can filter it out for regulator-facing reports.

# Run the smoke yourself:
node scripts/smoke-neural-trader-feature-attribution.mjs

Verification

bash plugins/ruflo-neural-trader/scripts/smoke.sh
# Expected: "11 passed, 0 failed"

Architecture Decisions

• ADR-0001 — ruflo-neural-trader plugin contract (already-compliant namespaces, 4-namespace claim, smoke as contract)
• ADR-117 — run heavy jobs (walk-forward / Monte-Carlo / sweep / training) on the Managed Agent cloud runtime (the trader-cloud-backtest skill + /trader cloud command), with cost-optimization rules
• ADR-115 — the managed_agent_* cloud runtime that ADR-117 builds on (lives in the ruflo-agent plugin)

Related Plugins

• ruflo-agent — the managed_agent_* cloud agent runtime used by the trader-cloud-backtest skill (ADR-115 / ADR-117)
• ruflo-agentdb — namespace convention owner; backing store
• ruflo-market-data — OHLCV data ingestion and candlestick pattern detection (feeds trading-strategies)
• ruflo-ruvector — HNSW indexing for strategy pattern similarity search
• ruflo-cost-tracker — PnL tracking and cost attribution
• ruflo-observability — Strategy performance dashboards

License

MIT