Introducing Neural Trader — Market Intelligence Built on Dynamic Graphs

## What is Neural Trader?

Neural Trader is a new module in RuVector that treats financial markets as **living graphs** instead of flat tables of price candles.

Every order, trade, cancellation, and venue event becomes a node or edge in a dynamic graph. The system watches this graph in real time and uses its structure to make decisions about when it's safe to learn, act, or store new information — and when it's not.

The core idea: **don't just predict what will happen — know when your predictions are trustworthy enough to act on.**

## Why Graphs Instead of Time Series?

A limit order book isn't just numbers over time. It has structure:

- Orders sit at **price levels** (queue position matters)
- Trades **match** specific orders (causality)
- Participants show **patterns** across symbols (cross-asset correlation)
- Market regimes **shift** between calm, normal, and volatile (context changes everything)

Traditional systems flatten all this into OHLCV bars and lose the relationships. Neural Trader keeps them as a typed graph where every connection has meaning.

## Architecture: Six Layers

```
Raw Market Data
    │
    ▼
┌─────────────────────────────────┐
│  L1: Ingest & Normalize         │  ← Standardize events from any venue
│  (neural-trader-core)           │
└────────────┬────────────────────┘
             │
             ▼
┌─────────────────────────────────┐
│  L2: Dynamic Graph              │  ← Build typed graph from events
│  (planned)                      │
└────────────┬────────────────────┘
             │
             ▼
┌─────────────────────────────────┐
│  L3: GNN + Attention            │  ← Learn embeddings from graph structure
│  (planned)                      │
└────────────┬────────────────────┘
             │
             ▼
┌─────────────────────────────────┐
│  L4: Memory & Replay            │  ← Store important experiences selectively
│  (neural-trader-replay)         │
└────────────┬────────────────────┘
             │
             ▼
┌─────────────────────────────────┐
│  L5: Coherence Gate             │  ← Safety check: is the system stable?
│  (neural-trader-coherence)      │
└────────────┬────────────────────┘
             │
             ▼
┌─────────────────────────────────┐
│  L6: Policy & Execution         │  ← Act only with verified permission
│  (planned)                      │
└─────────────────────────────────┘
```

## What's Built So Far (3 Crates, 12 Tests)

### `neural-trader-core` — The Language of Markets

Defines how market events are represented throughout the system.

| Type | What It Does |
|------|-------------|
| `MarketEvent` | Standardized envelope for any market event (order, trade, cancel, snapshot) |
| `EventType` | 7 event kinds: NewOrder, ModifyOrder, CancelOrder, Trade, BookSnapshot, SessionMarker, VenueStatus |
| `NodeKind` | 10 graph node types: Symbol, Venue, PriceLevel, Order, Trade, Event, Participant, TimeBucket, Regime, StrategyState |
| `EdgeKind` | 12 graph edge types: AtLevel, NextTick, Generated, Matched, ModifiedFrom, CanceledBy, and more |
| `PropertyKey` | 17 node properties: VisibleDepth, QueueLength, LocalImbalance, CancelHazard, SpreadDistance, etc. |
| `GraphDelta` | Describes what changed in the graph after processing one event |

Traits for building custom pipelines:
- `EventIngestor` — accepts raw market events
- `GraphUpdater` — projects events onto the graph
- `Embedder` — produces vector embeddings from graph state

### `neural-trader-coherence` — The Safety Gate

The coherence gate is the system's safety mechanism. It answers: **"Is the market stable enough right now for the system to safely learn, trade, or store memories?"**

It checks four signals:

| Signal | What It Measures | What Happens When It Fails |
|--------|-----------------|---------------------------|
| **MinCut value** | How strongly connected the local graph is | Low connectivity = fragile state, block actions |
| **CUSUM score** | Cumulative drift in parameters over time | High drift = regime is shifting, block learning |
| **Drift score** | How far embeddings have moved from last stable window | High drift = model may be stale, restrict operations |
| **Boundary stability** | How many consecutive windows had the same graph boundary | Unstable boundary = graph structure is changing, wait |

The gate uses **tiered permissions** — not all-or-nothing:

| Permission | Strictness | When It's Allowed |
|------------|-----------|-------------------|
| **Retrieve** | Least strict | Only needs MinCut above floor |
| **Write / Act** | Medium | Needs all four signals passing |
| **Learn** | Most strict | Needs all signals + drift below half the maximum |

This means: during a flash crash, the system can still **look up** past experiences (retrieve), but it won't **store new ones** (write) or **update its models** (learn) until things stabilize.

Regime-dependent thresholds:

| Regime | MinCut Floor | Meaning |
|--------|-------------|---------|
| Calm | 12 | Highest bar — stable markets should have strong graph connectivity |
| Normal | 9 | Standard operating threshold |
| Volatile | 6 | Lower bar — volatile markets naturally have weaker connectivity |

### `neural-trader-replay` — Selective Memory

Not every market tick deserves to be remembered. The replay store uses **selective admission** controlled by the coherence gate.

| Component | What It Does |
|-----------|-------------|
| `ReplaySegment` | A sealed window of events + embeddings + labels + coherence stats |
| `SegmentKind` | 7 categories: HighUncertainty, LargeImpact, RegimeTransition, StructuralAnomaly, RareQueuePattern, HeadDisagreement, Routine |
| `ReservoirStore` | Bounded buffer (VecDeque) with O(1) eviction — oldest segments are dropped when full |
| `InMemoryReceiptLog` | Witness receipt logger for audit trails |

The key rule: **if the coherence gate says "don't write," the replay store rejects the segment.** This prevents the system from memorizing experiences during unstable periods when the data may be misleading.

## What Makes This Different

| Traditional Trading Systems | Neural Trader |
|---------------------------|---------------|
| Flat OHLCV time series | Dynamic typed graph with 10 node types and 12 edge types |
| Learn from all data equally | Selective learning — only learns when the system is coherent |
| No structural awareness | MinCut measures graph connectivity as a fragility signal |
| Audit trails are an afterthought | Every state mutation produces a witness receipt |
| Risk checks wrap around the model | Risk is built into the architecture (coherence gate) |
| All-or-nothing kill switches | Tiered permissions (retrieve → write → learn) degrade gracefully |

## Getting Started

### Add to your Cargo.toml

```toml
[dependencies]
neural-trader-core = { path = "crates/neural-trader-core" }
neural-trader-coherence = { path = "crates/neural-trader-coherence" }
neural-trader-replay = { path = "crates/neural-trader-replay" }
```

### Basic usage

```rust
use neural_trader_coherence::*;

// Create a coherence gate with default thresholds
let gate = ThresholdGate::new(GateConfig::default());

// Evaluate current market conditions
let ctx = GateContext {
    symbol_id: 1,
    venue_id: 1,
    ts_ns: 1_000_000,
    mincut_value: 15,          // strong graph connectivity
    partition_hash: [0u8; 16],
    cusum_score: 1.0,          // low drift
    drift_score: 0.1,          // embeddings are stable
    regime: RegimeLabel::Calm,
    boundary_stable_count: 10, // stable for 10 windows
};

let decision = gate.evaluate(&ctx).unwrap();
assert!(decision.all_allowed()); // safe to learn, write, and act
```

### Run the tests

```bash
cargo test -p neural-trader-core -p neural-trader-coherence -p neural-trader-replay
# 12 tests pass (2 core + 7 coherence + 3 replay)
```

## Roadmap

| Crate | Layer | Status | Description |
|-------|-------|--------|-------------|
| `neural-trader-core` | L1 | Shipped (PR #244) | Market event types and ingest traits |
| `neural-trader-coherence` | L5 | Shipped (PR #244) | MinCut coherence gate with CUSUM drift |
| `neural-trader-replay` | L4 | Shipped (PR #244) | Reservoir store with proof-gated writes |
| `neural-trader-graph` | L2 | Planned | Build typed graphs from order book events |
| `neural-trader-gnn` | L3 | Planned | GNN embeddings + temporal attention |
| `neural-trader-policy` | L6 | Planned | Position sizing with Kelly criterion |
| `neural-trader-backtest` | — | Planned | Historical replay and PnL tracking |
| `neural-trader-risk` | — | Planned | VaR, drawdown limits, exposure caps |
| `neural-trader-feed` | — | Planned | WebSocket/FIX market data adapters |
| `neural-trader-cli` | — | Planned | CLI for backtesting and live research |

## Links

- **PR**: #244
- **Tracking issue**: #245
- **Architecture**: [ADR-085](https://github.com/ruvnet/ruvector/blob/main/docs/adr/ADR-085-neural-trader-ruvector.md)
- **Source**: [`crates/neural-trader-*`](https://github.com/ruvnet/ruvector/tree/main/crates)

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Introducing Neural Trader — Market Intelligence Built on Dynamic Graphs #246

What is Neural Trader?

Why Graphs Instead of Time Series?

Architecture: Six Layers

What's Built So Far (3 Crates, 12 Tests)

`neural-trader-core` — The Language of Markets

`neural-trader-coherence` — The Safety Gate

`neural-trader-replay` — Selective Memory

What Makes This Different

Getting Started

Add to your Cargo.toml

Basic usage

Run the tests

Roadmap

Links

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Type	What It Does
`MarketEvent`	Standardized envelope for any market event (order, trade, cancel, snapshot)
`EventType`	7 event kinds: NewOrder, ModifyOrder, CancelOrder, Trade, BookSnapshot, SessionMarker, VenueStatus
`NodeKind`	10 graph node types: Symbol, Venue, PriceLevel, Order, Trade, Event, Participant, TimeBucket, Regime, StrategyState
`EdgeKind`	12 graph edge types: AtLevel, NextTick, Generated, Matched, ModifiedFrom, CanceledBy, and more
`PropertyKey`	17 node properties: VisibleDepth, QueueLength, LocalImbalance, CancelHazard, SpreadDistance, etc.
`GraphDelta`	Describes what changed in the graph after processing one event

Signal	What It Measures	What Happens When It Fails
MinCut value	How strongly connected the local graph is	Low connectivity = fragile state, block actions
CUSUM score	Cumulative drift in parameters over time	High drift = regime is shifting, block learning
Drift score	How far embeddings have moved from last stable window	High drift = model may be stale, restrict operations
Boundary stability	How many consecutive windows had the same graph boundary	Unstable boundary = graph structure is changing, wait

Permission	Strictness	When It's Allowed
Retrieve	Least strict	Only needs MinCut above floor
Write / Act	Medium	Needs all four signals passing
Learn	Most strict	Needs all signals + drift below half the maximum

Regime	MinCut Floor	Meaning
Calm	12	Highest bar — stable markets should have strong graph connectivity
Normal	9	Standard operating threshold
Volatile	6	Lower bar — volatile markets naturally have weaker connectivity

Component	What It Does
`ReplaySegment`	A sealed window of events + embeddings + labels + coherence stats
`SegmentKind`	7 categories: HighUncertainty, LargeImpact, RegimeTransition, StructuralAnomaly, RareQueuePattern, HeadDisagreement, Routine
`ReservoirStore`	Bounded buffer (VecDeque) with O(1) eviction — oldest segments are dropped when full
`InMemoryReceiptLog`	Witness receipt logger for audit trails

Traditional Trading Systems	Neural Trader
Flat OHLCV time series	Dynamic typed graph with 10 node types and 12 edge types
Learn from all data equally	Selective learning — only learns when the system is coherent
No structural awareness	MinCut measures graph connectivity as a fragility signal
Audit trails are an afterthought	Every state mutation produces a witness receipt
Risk checks wrap around the model	Risk is built into the architecture (coherence gate)
All-or-nothing kill switches	Tiered permissions (retrieve → write → learn) degrade gracefully

Crate	Layer	Status	Description
`neural-trader-core`	L1	Shipped (PR #244)	Market event types and ingest traits
`neural-trader-coherence`	L5	Shipped (PR #244)	MinCut coherence gate with CUSUM drift
`neural-trader-replay`	L4	Shipped (PR #244)	Reservoir store with proof-gated writes
`neural-trader-graph`	L2	Planned	Build typed graphs from order book events
`neural-trader-gnn`	L3	Planned	GNN embeddings + temporal attention
`neural-trader-policy`	L6	Planned	Position sizing with Kelly criterion
`neural-trader-backtest`	—	Planned	Historical replay and PnL tracking
`neural-trader-risk`	—	Planned	VaR, drawdown limits, exposure caps
`neural-trader-feed`	—	Planned	WebSocket/FIX market data adapters
`neural-trader-cli`	—	Planned	CLI for backtesting and live research

Introducing Neural Trader — Market Intelligence Built on Dynamic Graphs #246

Description

What is Neural Trader?

Why Graphs Instead of Time Series?

Architecture: Six Layers

What's Built So Far (3 Crates, 12 Tests)

neural-trader-core — The Language of Markets

neural-trader-coherence — The Safety Gate

neural-trader-replay — Selective Memory

What Makes This Different

Getting Started

Add to your Cargo.toml

Basic usage

Run the tests

Roadmap

Links

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions

`neural-trader-core` — The Language of Markets

`neural-trader-coherence` — The Safety Gate

`neural-trader-replay` — Selective Memory