npm package: @neural-trader/core
Description: Ultra-low latency neural trading engine with Rust + Node.js bindings
Author: Neural Trader Team
Latest version: 2.0.0

# Neural Trader 2.0 - Rust Implementation

[![CI Status](https://github.com/ruvnet/neural-trader/workflows/Rust%20CI/badge.svg)](https://github.com/ruvnet/neural-trader/actions)
[![codecov](https://codecov.io/gh/ruvnet/neural-trader/branch/main/graph/badge.svg)](https://codecov.io/gh/ruvnet/neural-trader)
[![License](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue.svg)](LICENSE)
[![npm version](https://badge.fury.io/js/%40neural-trader%2Fcore.svg)](https://www.npmjs.com/package/@neural-trader/core)

High-performance algorithmic trading system written in Rust with Node.js bindings. Delivers **10-100x performance improvements** over Python implementations while maintaining feature parity.

## Features

- **8 Trading Strategies**: Momentum, Mean Reversion, Pairs Trading, Market Making, Statistical Arbitrage, ML-Enhanced, Risk Parity, Multi-Factor
- **Ultra-Low Latency**: <200ms order execution, <50ms risk checks
- **Real-Time Risk Management**: Position limits, drawdown controls, dynamic stops
- **AgentDB Integration**: Self-learning with 150x faster vector search
- **Multi-Exchange Support**: Alpaca, Binance, with extensible broker abstraction
- **Node.js Bindings**: Use from JavaScript/TypeScript via napi-rs
- **CLI Interface**: Comprehensive command-line tools
- **Production Ready**: Docker, CI/CD, monitoring, observability

## Performance Benchmarks

| Operation | Python | Rust | Speedup |
|-----------|--------|------|---------|
| Strategy Execution | 1,200ms | 150ms | **8x** |
| Risk Calculation | 450ms | 35ms | **13x** |
| Portfolio Rebalancing | 800ms | 60ms | **13x** |
| Backtesting (1 year) | 45min | 4min | **11x** |
| Memory Usage | 850MB | 45MB | **19x** |

## Quick Start

### Installation

#### Via npm (Node.js) - Modular Packages

Neural Trader offers a **plugin-style architecture** - install only what you need!

**Core Types (Required)**:
```bash
npm install @neural-trader/core
```

**Functional Packages** (install what you need):
```bash
# Backtesting
npm install @neural-trader/backtesting

# AI-Powered Forecasting
npm install @neural-trader/neural

# Risk Management
npm install @neural-trader/risk

# Trading Strategies
npm install @neural-trader/strategies

# Sports Betting & Prediction Markets
npm install @neural-trader/sports-betting @neural-trader/prediction-markets

# Full Platform (all features)
npm install neural-trader
```

**Package Sizes**:
- `@neural-trader/core`: 3.4 KB (types only)
- Individual packages: 250-1,200 KB each
- Full platform: ~5 MB

See [packages/README.md](./packages/README.md) for complete package documentation.

#### Via Cargo (Rust)

```bash
cargo install neural-trader-cli
```

#### Via Docker

```bash
docker pull neuraltrader/neural-trader-rust:latest
```

### Basic Usage

#### CLI

```bash
# Initialize a new strategy
neural-trader init my-strategy --template momentum

# Backtest the strategy
cd my-strategy
neural-trader backtest --start 2024-01-01 --end 2024-12-31

# Run live (paper trading)
neural-trader run --config config/production.toml --paper
```

#### Node.js

```javascript
const { NeuralTrader, MomentumStrategy } = require('@neural-trader/core');

async function main() {
  // Initialize trader
  const trader = new NeuralTrader({
    apiKey: process.env.ALPACA_API_KEY,
    apiSecret: process.env.ALPACA_API_SECRET,
    paperTrading: true
  });

  // Create strategy
  const strategy = new MomentumStrategy({
    symbols: ['AAPL', 'MSFT', 'GOOGL'],
    lookbackPeriod: 20,
    minMomentum: 0.02
  });

  // Run strategy
  await trader.addStrategy(strategy);
  await trader.start();
}

main().catch(console.error);
```

#### Rust

```rust
use neural_trader::prelude::*;

#[tokio::main]
async fn main() -> Result<()> {
    // Initialize trader
    let config = Config::from_file(".config/production.toml")?;
    let mut trader = Trader::new(config).await?;

    // Create momentum strategy
    let strategy = MomentumStrategy::builder()
        .symbols(vec!["AAPL", "MSFT", "GOOGL"])
        .lookback_period(20)
        .min_momentum(0.02)
        .build()?;

    // Add strategy and run
    trader.add_strategy(Box::new(strategy)).await?;
    trader.run().await?;

    Ok(())
}
```

## Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                     Neural Trader Core                       │
├─────────────────────────────────────────────────────────────┤
│                                                               │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐       │
│  │   Market     │  │  Strategies  │  │  Execution   │       │
│  │   Data       │  │  Engine      │  │  Engine      │       │
│  └──────────────┘  └──────────────┘  └──────────────┘       │
│                                                               │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐       │
│  │  Portfolio   │  │     Risk     │  │   Neural     │       │
│  │  Manager     │  │   Manager    │  │   Engine     │       │
│  └──────────────┘  └──────────────┘  └──────────────┘       │
│                                                               │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐       │
│  │   AgentDB    │  │  Backtesting │  │  Governance  │       │
│  │   Client     │  │   Engine     │  │   System     │       │
│  └──────────────┘  └──────────────┘  └──────────────┘       │
│                                                               │
└─────────────────────────────────────────────────────────────┘
         │                    │                    │
         ▼                    ▼                    ▼
   ┌──────────┐        ┌──────────┐        ┌──────────┐
   │  NAPI    │        │   CLI    │        │  Docker  │
   │ Bindings │        │  Binary  │        │  Image   │
   └──────────┘        └──────────┘        └──────────┘
```

### Workspace Structure

```
neural-trader-rust/
├── crates/
│   ├── core/              # Core types and traits
│   ├── market-data/       # Market data providers
│   ├── features/          # Technical indicators
│   ├── strategies/        # 8 trading strategies
│   ├── execution/         # Order execution
│   ├── portfolio/         # Portfolio management
│   ├── risk/              # Risk management
│   ├── backtesting/       # Backtesting engine
│   ├── neural/            # Neural network integration
│   ├── agentdb-client/    # AgentDB persistent memory
│   ├── streaming/         # Real-time data streaming
│   ├── governance/        # Governance and compliance
│   ├── cli/               # Command-line interface
│   ├── napi-bindings/     # Node.js bindings
│   └── utils/             # Shared utilities
├── .config/               # Configuration templates
├── tests/                 # Integration & E2E tests
├── benches/              # Performance benchmarks
├── examples/             # Usage examples
└── docs/                 # Documentation
```

## Trading Strategies

### 1. Momentum Strategy
Captures price momentum using RSI, MACD, and moving averages.

```rust
MomentumStrategy::builder()
    .symbols(vec!["AAPL", "MSFT"])
    .lookback_period(20)
    .min_momentum(0.02)
    .build()?
```

### 2. Mean Reversion Strategy
Trades mean-reverting securities using Bollinger Bands and Z-scores.

```rust
MeanReversionStrategy::builder()
    .symbols(vec!["SPY", "QQQ"])
    .lookback_period(50)
    .z_score_threshold(2.0)
    .build()?
```

### 3. Pairs Trading Strategy
Statistical arbitrage on cointegrated pairs.

```rust
PairsTradingStrategy::builder()
    .pairs(vec![("AAPL", "MSFT"), ("GLD", "SLV")])
    .lookback_period(100)
    .entry_threshold(2.0)
    .exit_threshold(0.5)
    .build()?
```

### 4. Market Making Strategy
Provides liquidity with bid-ask spread capture.

```rust
MarketMakingStrategy::builder()
    .symbols(vec!["BTC/USDT"])
    .spread_bps(20)
    .order_size(0.1)
    .max_inventory(10.0)
    .build()?
```

### 5. Statistical Arbitrage
Multi-asset statistical relationships.

```rust
StatArbStrategy::builder()
    .basket(vec!["AAPL", "MSFT", "GOOGL", "AMZN"])
    .lookback_period(60)
    .z_score_threshold(2.5)
    .build()?
```

### 6. ML-Enhanced Strategy
Neural network predictions combined with traditional signals.

```rust
MLEnhancedStrategy::builder()
    .symbols(vec!["AAPL"])
    .model_path("models/lstm_predictor.onnx")
    .confidence_threshold(0.7)
    .build()?
```

### 7. Risk Parity Strategy
Portfolio allocation based on risk contribution.

```rust
RiskParityStrategy::builder()
    .universe(vec!["SPY", "TLT", "GLD", "VNQ"])
    .rebalance_frequency(Duration::days(30))
    .target_volatility(0.12)
    .build()?
```

### 8. Multi-Factor Strategy
Combines multiple factors (value, momentum, quality).

```rust
MultiFactorStrategy::builder()
    .universe(sp500_tickers())
    .factors(vec![
        Factor::Value { weight: 0.3 },
        Factor::Momentum { weight: 0.4 },
        Factor::Quality { weight: 0.3 }
    ])
    .rebalance_frequency(Duration::days(30))
    .build()?
```

## Configuration

Configuration files use TOML format with environment variable substitution:

```toml
[environment]
name = "production"
log_level = "info"

[market_data.alpaca]
api_key = "${ALPACA_API_KEY}"
api_secret = "${ALPACA_API_SECRET}"

[risk]
max_portfolio_drawdown = 0.15
max_position_size = 0.10
```

See [.config/README.md](.config/README.md) for full configuration documentation.

## Development

### Prerequisites

- Rust 1.75+
- Node.js 18+ (for npm package)
- PostgreSQL 14+ (optional, for persistent storage)
- Redis 7+ (optional, for caching)

### Building from Source

```bash
# Clone repository
git clone https://github.com/ruvnet/neural-trader.git
cd neural-trader/neural-trader-rust

# Build all crates
cargo build --workspace

# Run tests
cargo test --workspace

# Run benchmarks
cargo bench --workspace

# Build Node.js bindings
npm run build

# Build Docker image
docker build -t neural-trader .
```

### Running Tests

```bash
# Unit tests
cargo test --workspace

# Integration tests
cargo test --test '*' --workspace

# End-to-end tests
cargo test --test test_full_trading_loop

# Property tests
cargo test --test 'test_pnl' --features proptest

# With coverage
cargo tarpaulin --workspace --timeout 300
```

### Running Benchmarks

```bash
# All benchmarks
cargo bench --workspace

# Specific benchmark
cargo bench --bench strategy_benchmarks

# Compare with baseline
cargo bench --workspace -- --save-baseline main
```

## Docker Deployment

### Using Docker Compose

```bash
# Start all services (app + postgres + redis + monitoring)
docker-compose up -d

# View logs
docker-compose logs -f neural-trader

# Stop services
docker-compose down
```

### Standalone Container

```bash
# Run with configuration file
docker run -v $(pwd)/config.toml:/app/config.toml \
  -e ALPACA_API_KEY=$ALPACA_API_KEY \
  neuraltrader/neural-trader-rust:latest

# Run with environment variables only
docker run \
  -e DATABASE_URL=$DATABASE_URL \
  -e ALPACA_API_KEY=$ALPACA_API_KEY \
  neuraltrader/neural-trader-rust:latest
```

## CI/CD

The project uses GitHub Actions for continuous integration:

- **Format Check**: Ensures code formatting with `rustfmt`
- **Lint**: Runs `clippy` for code quality
- **Test**: Multi-platform tests (Linux/macOS/Windows, stable/nightly)
- **Coverage**: Code coverage with `tarpaulin`
- **Security Audit**: Dependency vulnerability scanning
- **License Check**: Ensures license compliance
- **Benchmarks**: Performance regression detection
- **Release**: Automated binary builds and npm publishing

See [.github/workflows/rust-ci.yml](.github/workflows/rust-ci.yml) for details.

## Monitoring and Observability

### Metrics (Prometheus)

- Request latency (p50, p95, p99)
- Order execution time
- Strategy performance
- Risk metrics
- System resources

Access at `http://localhost:9090` (Prometheus) or `http://localhost:3000` (Grafana).

### Tracing (Jaeger)

Distributed tracing for request flows across services.

Access at `http://localhost:16686`.

### Logging

Structured JSON logs with tracing integration:

```rust
tracing::info!(
    symbol = %order.symbol,
    quantity = order.quantity,
    price = %order.price,
    "Order executed successfully"
);
```

## API Documentation

### REST API

```bash
# Start server
neural-trader serve --port 8080

# Health check
curl http://localhost:8080/health

# Get portfolio
curl http://localhost:8080/api/v1/portfolio

# Submit order
curl -X POST http://localhost:8080/api/v1/orders \
  -H "Content-Type: application/json" \
  -d '{"symbol":"AAPL","quantity":10,"side":"buy"}'
```

### WebSocket API

```javascript
const ws = new WebSocket('ws://localhost:8080/ws');

ws.on('message', (data) => {
  const message = JSON.parse(data);
  console.log('Market data:', message);
});

ws.send(JSON.stringify({
  type: 'subscribe',
  symbols: ['AAPL', 'MSFT']
}));
```

## AgentDB Integration

Neural Trader uses AgentDB for persistent memory and self-learning:

```rust
use neural_trader::agentdb::AgentDBClient;

// Store trading decision
client.store_memory(
    "decision",
    &json!({
        "strategy": "momentum",
        "action": "buy",
        "symbol": "AAPL",
        "confidence": 0.85
    })
).await?;

// Query similar past decisions
let similar = client.query_similar(
    "What were successful trades for AAPL?",
    5
).await?;

// Learn from outcomes
client.train_pattern(
    &decision_embedding,
    outcome.pnl,
    0.01  // learning rate
).await?;
```

## License

This project is dual-licensed under MIT OR Apache-2.0. See [LICENSE-MIT](LICENSE-MIT) and [LICENSE-APACHE](LICENSE-APACHE) for details.

## Contributing

Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

### Development Workflow

1. Fork the repository
2. Create a feature branch (`git checkout -b feat/amazing-feature`)
3. Make changes and add tests
4. Run tests and linting (`cargo test && cargo clippy`)
5. Commit changes (`git commit -m 'feat: add amazing feature'`)
6. Push to branch (`git push origin feat/amazing-feature`)
7. Open a Pull Request

## Security

For security issues, please see [SECURITY.md](SECURITY.md) for our security policy and reporting process.

## Support

- Documentation: https://neural-trader.ruv.io
- Issues: https://github.com/ruvnet/neural-trader/issues
- Discord: https://discord.gg/neural-trader
- Email: support@neural-trader.io

## Roadmap

- [ ] Additional exchanges (Coinbase, Kraken)
- [ ] Options trading support
- [ ] Advanced order types (iceberg, TWAP, VWAP)
- [ ] Multi-account management
- [ ] Backtesting UI dashboard
- [ ] Mobile app for monitoring
- [ ] Telegram bot integration
- [ ] Social trading features

## Acknowledgments

- Built with [Rust](https://www.rust-lang.org/)
- Node.js bindings via [napi-rs](https://napi.rs/)
- AgentDB for self-learning capabilities
- Inspired by the original Neural Trader Python implementation

---

**Disclaimer**: This software is for educational and research purposes only. Trading financial instruments carries risk. Past performance does not guarantee future results. Use at your own risk.