@neural-trader/predictor


Conformal prediction SDK for neural trading with mathematically guaranteed prediction intervals

> Part of the Neural Trader ecosystem - AI-powered algorithmic trading platform
> Built by rUv | GitHub

A production-ready TypeScript/JavaScript library providing distribution-free prediction intervals with rigorous mathematical guarantees. Available in three high-performance implementations (Pure JS, WebAssembly, Native Node.js bindings) to fit any deployment environment - from browsers to high-frequency trading servers.

🌟 Why Conformal Prediction?

Traditional machine learning gives you point estimates that are often wrong. Conformal prediction gives you guaranteed intervals:

``
Traditional ML: "Bitcoin will be $50,000" (70% chance you're wrong)
Conformal ML: "Bitcoin will be between $48,500-$51,500" (90% mathematical guarantee)
`

This makes conformal prediction essential for:
- Risk Management: Know your worst-case scenarios with probability guarantees
- Automated Trading: Set stop-losses and take-profits with statistical confidence
- Regulatory Compliance: Provable uncertainty quantification for audits
- Portfolio Optimization: Reliable confidence bounds for position sizing

Core Principle

Conformal prediction provides a mathematical guarantee:

`
P(y ∈ [lower, upper]) ≥ 1 - α
`

Get guaranteed intervals instead of uncertain point estimates. Perfect for trading, risk management, and any application requiring reliable uncertainty quantification.

🎯 Key Features

- Multiple Implementations:
- Pure JavaScript (portable, works everywhere)
- WebAssembly (5-10x faster, zero dependencies)
- Native Node.js bindings (near-Rust performance)
- Auto-detection with fallback support
- Split Conformal Prediction: Distribution-free intervals with (1-α) coverage guarantee
- Adaptive Conformal Inference (ACI): PID-controlled dynamic coverage adjustment
- Conformalized Quantile Regression (CQR): Quantile-based intervals with guarantees
- Multiple Nonconformity Scores: Absolute, normalized, and quantile-based
- Real-time Streaming: Efficient incremental updates
- Trading Integration: Seamless integration with @neural-trader/neural
- Browser & Node.js: Works in browsers, Node.js, Electron, React Native
- TypeScript Support: Full type definitions, 100% type-safe

💼 Real-World Use Cases

$3


`typescript
// Set stop-loss and take-profit with 95% confidence
const interval = predictor.predict(nextPrice);
executeTrade({
entry: interval.point,
stopLoss: interval.lower, // 95% confident price won't go below
takeProfit: interval.upper, // 95% confident price won't exceed
});
`

$3

`typescript
// Calculate Value-at-Risk with guaranteed coverage
const returns = calculatePortfolioReturns(positions);
const interval = predictor.predict(expectedReturn);
const VaR95 = interval.lower; // 95% confidence lower bound
const maxLoss = portfolio.value * VaR95;
`

$3

`typescript
// Get reliable bounds for option premiums
const optionInterval = predictor.predict(blackScholesPrice);
const conservativeBid = optionInterval.lower;
const conservativeAsk = optionInterval.upper;
`

$3

`typescript
// Sub-millisecond predictions with WASM
const predictor = new WasmConformalPredictor({ alpha: 0.05 });
for (const tick of marketTicks) {
const interval = predictor.predict(tick.midPrice); // <500μs
if (interval.width() < SPREAD_THRESHOLD) {
placeMarketMakerOrder(interval.lower, interval.upper);
}
}
`

$3

`typescript
// Generate audit-ready predictions with formal guarantees
const report = {
prediction: interval.point,
lowerBound: interval.lower,
upperBound: interval.upper,
coverage: "95%", // Mathematically proven
method: "Split Conformal Prediction",
regulatoryCompliant: true,
};
`

📊 Performance Comparison

| Implementation | Prediction | Calibration | Memory | Browser | Node.js |
|---|---|---|---|---|---|
| Rust (native) | <50μs | <20ms | <5MB | - | ✓ |
| WASM | <500μs | <150ms | <15MB | ✓ | ✓ |
| Pure JS | <2ms | <500ms | <25MB | ✓ | ✓ |

Real-world targets:
- Prediction latency: <1ms (guaranteed interval)
- Calibration time: <100ms for 2,000 samples
- Throughput: 10,000+ predictions/second
- Memory footprint: <10MB for typical usage

🚀 Quick Start

$3

`bash
npm install @neural-trader/predictor


or

yarn add @neural-trader/predictor

or

pnpm add @neural-trader/predictor
`

$3

`typescript
import { ConformalPredictor, AbsoluteScore } from '@neural-trader/predictor';

const predictor = new ConformalPredictor({
alpha: 0.1, // 90% coverage
scoreFunction: new AbsoluteScore(),
});

// Calibrate with historical data
await predictor.calibrate(
[100.0, 105.0, 98.0, 102.0],
[102.0, 104.0, 99.0, 101.0]
);

// Make prediction with guaranteed interval
const interval = predictor.predict(103.0);
console.log(Prediction: ${interval.point});
console.log(90% Confidence: [${interval.lower}, ${interval.upper}]);
console.log(Interval width: ${interval.width()});
console.log(Coverage: ${interval.coverage() * 100}%);
`

$3

`typescript
import { initWasm, WasmConformalPredictor } from '@neural-trader/predictor/wasm';

// Initialize WASM module once
await initWasm();

// Use same API, but with Rust performance
const predictor = new WasmConformalPredictor({
alpha: 0.1,
scoreFunction: 'absolute', // String enum for WASM
});

await predictor.calibrate(predictions, actuals);
const interval = predictor.predict(103.0);
// 5-10x faster than pure JS
`

$3

`typescript
import { NativeConformalPredictor } from '@neural-trader/predictor/native';

// Try native bindings (requires Node.js >= 18)
const predictor = new NativeConformalPredictor({
alpha: 0.1,
scoreFunction: 'absolute',
});

await predictor.calibrate(predictions, actuals);
const interval = predictor.predict(103.0);
// Near-Rust performance (fastest option)
`

$3

`typescript
import { createPredictor } from '@neural-trader/predictor';

// Automatically chooses: Native > WASM > Pure JS
const predictor = await createPredictor({
alpha: 0.1,
preferNative: true,
fallbackToWasm: true,
});

console.log(Using: ${predictor.implementation}); // "native" | "wasm" | "pure"
`

📚 Adaptive Trading Example

`typescript
import { AdaptiveConformalPredictor } from '@neural-trader/predictor';

const predictor = new AdaptiveConformalPredictor({
targetCoverage: 0.90, // Maintain 90% coverage
gamma: 0.02, // Learning rate
scoreFunction: new AbsoluteScore(),
});

// Stream market predictions
for await (const { prediction, actual } of marketDataStream) {
// Get interval and adapt coverage based on outcome
const interval = await predictor.predictAndAdapt(prediction, actual);

// Make trading decision based on interval
if (interval.width() < MAX_INTERVAL_WIDTH && interval.point > THRESHOLD) {
console.log(TRADE: Buy at ${interval.point});
console.log(Risk: Short at ${interval.lower});
console.log(Target: Long at ${interval.upper});

await executeTrade({
type: 'BUY',
quantity: positionSize,
stopLoss: interval.lower,
takeProfit: interval.upper,
});
}

// Monitor coverage adaptation
const metrics = await predictor.getMetrics();
console.log(Coverage: ${metrics.empiricalCoverage * 100}%);
console.log(Current alpha: ${metrics.currentAlpha});
}
`

🌐 Browser Usage

`html






Make Prediction





`

📖 API Reference

$3

`typescript
class ConformalPredictor {
constructor(config: PredictorConfig);

// Core methods
calibrate(predictions: number[], actuals: number[]): Promise;
predict(pointPrediction: number): PredictionInterval;
update(pointPrediction: number, actual: number): Promise;

// Configuration
setAlpha(alpha: number): void;
getAlpha(): number;

// Metrics
getMetrics(): Promise;
empiricalCoverage(): number;
}
`

$3

`typescript
class AdaptiveConformalPredictor {
constructor(config: AdaptiveConfig);

// Adaptive inference
predictAndAdapt(
pointPrediction: number,
actual?: number
): Promise;

// Monitoring
empiricalCoverage(): number;
currentAlpha(): number;
getMetrics(): Promise;
}
`

$3

`typescript
interface PredictionInterval {
point: number; // Point prediction
lower: number; // Lower bound
upper: number; // Upper bound
alpha: number; // Miscoverage rate
quantile: number; // Threshold quantile
timestamp: number; // Prediction timestamp

// Methods
width(): number; // Interval width
contains(value: number): boolean; // Check if value in interval
relativeWidth(): number; // Width as % of point
coverage(): number; // Expected coverage (1-α)
}
`

$3

`typescript
interface PredictorConfig {
alpha: number; // 0.01-0.30 (default: 0.1)
scoreFunction: ScoreFunction; // AbsoluteScore | NormalizedScore | QuantileScore
calibrationSize?: number; // 1000-5000 (default: 2000)
recalibrationFreq?: number; // Predictions before recalib (default: 100)
maxIntervalWidthPct?: number; // 1-10% (default: 5.0)
monitoring?: {
enabled: boolean;
metricsInterval: number; // ms (default: 5000)
};
}

interface AdaptiveConfig {
targetCoverage: number; // 0.80-0.99 (default: 0.90)
gamma: number; // 0.01-0.05 (default: 0.02)
coverageWindow?: number; // Window size for tracking (default: 200)
alphaMin?: number; // Min alpha (default: 0.01)
alphaMax?: number; // Max alpha (default: 0.30)
scoreFunction: ScoreFunction;
}
`

$3

`typescript
import {
AbsoluteScore,
NormalizedScore,
QuantileScore,
} from '@neural-trader/predictor';

// Absolute difference
const absolute = new AbsoluteScore();

// Normalized by prediction magnitude
const normalized = new NormalizedScore({ epsilon: 1e-6 });

// Quantile-based for asymmetric intervals
const quantile = new QuantileScore({ qLow: 0.05, qHigh: 0.95 });
`

🔗 Integration with @neural-trader/neural

Seamlessly combine neural predictions with conformal intervals:

`typescript
import { NeuralPredictor } from '@neural-trader/neural';
import { wrapWithConformal } from '@neural-trader/predictor';

// Load neural model
const neural = new NeuralPredictor({
modelPath: './model.onnx',
device: 'gpu',
});

// Wrap with conformal guarantees
const conformal = wrapWithConformal(neural, {
alpha: 0.1,
calibrationSize: 2000,
adaptive: true,
gamma: 0.02,
});

// Get predictions with guaranteed intervals
const features = loadFeatures();
const result = await conformal.predict(features);

console.log(Point: ${result.point});
console.log(Interval: [${result.lower}, ${result.upper}]);
console.log(Coverage: ${result.coverage() * 100}%);

// Make trading decision with confidence
if (result.width() < 5 && result.point > 100) {
await executeOrder({
symbol: 'AAPL',
quantity: 100,
stopLoss: result.lower,
takeProfit: result.upper,
});
}
`

🎯 Trading Decision Engine

`typescript
import { TradingDecisionEngine } from '@neural-trader/predictor';

const engine = new TradingDecisionEngine({
predictor: conformalPredictor,
maxIntervalWidthPct: 5.0,
minConfidence: 0.85,
kellyFraction: 0.25,
riskRewardRatio: 1.5,
});

const decision = await engine.evaluate(marketFeatures);

if (decision.shouldTrade) {
console.log(Signal: ${decision.signal}); // "buy" | "sell" | "hold"
console.log(Position Size: ${decision.positionSize}%);
console.log(Edge: ${decision.edge}%);
console.log(Risk: ${decision.risk}%);
console.log(Expected Sharpe: ${decision.expectedSharpe});

await executor.execute({
side: decision.signal,
quantity: decision.positionSize,
stopLoss: decision.stopLoss,
takeProfit: decision.takeProfit,
});
}
`

📊 Performance Monitoring

`typescript
import { PredictorMonitor } from '@neural-trader/predictor';

const monitor = new PredictorMonitor(predictor);

// Real-time metrics
setInterval(async () => {
const metrics = await monitor.getMetrics();

console.log(
Coverage: ${(metrics.empiricalCoverage * 100).toFixed(2)}%
Avg Width: ${metrics.avgIntervalWidth.toFixed(4)}
Width Std Dev: ${metrics.widthStdDev.toFixed(4)}
Latency p50: ${metrics.latencyP50.toFixed(2)}ms
Latency p95: ${metrics.latencyP95.toFixed(2)}ms
Latency p99: ${metrics.latencyP99.toFixed(2)}ms
Calibration Age: ${metrics.calibrationAgeSeconds}s
);

// Health checks
if (!monitor.isHealthy()) {
console.warn('⚠️ Predictor health issues:', monitor.getIssues());

// Trigger recalibration if needed
if (metrics.calibrationAgeSeconds > 300) {
await recalibrate();
}
}
}, 5000);
`

🧪 Testing Utilities

`typescript
import {
generateSyntheticData,
evaluateCoverage,
compareMethods,
performanceBenchmark,
} from '@neural-trader/predictor/testing';

// Generate test data
const { predictions, actuals } = generateSyntheticData({
size: 10000,
distribution: 'normal',
noise: 0.1,
seed: 42,
});

// Evaluate coverage
const results = evaluateCoverage(predictor, predictions, actuals);
console.log(Empirical Coverage: ${results.empiricalCoverage * 100}%);
console.log(Expected Coverage: ${(1 - predictor.alpha) * 100}%);
console.log(Avg Width: ${results.avgWidth});

// Compare different implementations
const comparison = await compareMethods({
methods: ['conformal', 'bootstrap', 'mcDropout'],
testData: { predictions, actuals },
metrics: ['coverage', 'width', 'latency', 'memory'],
});

console.table(comparison);

// Benchmark performance
const bench = await performanceBenchmark(predictor, {
iterations: 10000,
calibrationSizes: [1000, 2000, 5000],
memoryProfile: true,
});

console.log(Throughput: ${bench.throughput} predictions/sec);
console.log(Memory Peak: ${bench.memoryPeak}MB);
`

🌍 Browser Support

| Browser | Version | Status |
|---------|---------|--------|
| Chrome | 90+ | ✓ Full support |
| Firefox | 88+ | ✓ Full support |
| Safari | 14+ | ✓ Full support |
| Edge | 90+ | ✓ Full support |
| Mobile (iOS) | 14+ | ✓ Full support |
| Mobile (Android) | 10+ | ✓ Full support |

WASM support requires browsers with WebAssembly support (all modern browsers).

📦 Build Targets

The package is built for multiple targets:

`javascript
// CommonJS (Node.js)
const { ConformalPredictor } = require('@neural-trader/predictor');

// ES Modules
import { ConformalPredictor } from '@neural-trader/predictor';

// WASM (high-performance)
import { WasmConformalPredictor } from '@neural-trader/predictor/wasm';

// Native (Node.js only)
import { NativeConformalPredictor } from '@neural-trader/predictor/native';
`

🚀 Examples

See the /examples directory for complete working examples:

- basic.ts - Simple conformal prediction
- trading.ts - Real trading integration example

Run examples:

`bash
npm run build
npm run bench
`

🧠 Mathematical Background

$3

For calibration samples with nonconformity scores:

`
Quantile = ceil((n+1)(1-α)) / n
`

Prediction interval guarantees:

`
P(y ∈ [pred - Quantile, pred + Quantile]) ≥ 1 - α
`

$3

Dynamically adjusts α using PID control:

`
α_new = α - γ × (observed_coverage - target_coverage)
`

With constraints: α_min ≤ α_new ≤ α_max

📝 Logging & Debugging

`typescript
// Enable debug logging
localStorage.setItem('log-level', 'debug');

// Or in Node.js
process.env.DEBUG = 'neural-trader:*';
`

Log levels: error, warn, info, debug, trace

🔒 Error Handling

`typescript
import { PredictionError, ConfigError, CalibrationError } from '@neural-trader/predictor';

try {
const interval = await predictor.predict(value);
} catch (error) {
if (error instanceof CalibrationError) {
// Handle calibration issues
console.error('Calibration failed:', error.message);
await recalibrate();
} else if (error instanceof ConfigError) {
// Handle configuration issues
console.error('Invalid configuration:', error.message);
} else if (error instanceof PredictionError) {
// Handle prediction issues
console.error('Prediction failed:', error.message);
}
}
`

🤝 Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Run tests: npm run test
5. Format code: npm run lint`
6. Submit a pull request

📄 License

Licensed under either of:

- Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

🔗 Resources

- Conformal Prediction Theory
- Adaptive Conformal Inference
- Conformalized Quantile Regression
- Repository
- Rust Crate

⚡ Roadmap

- [x] Pure JavaScript implementation
- [x] WASM bindings
- [x] NAPI-rs native addon
- [x] Adaptive conformal inference
- [x] Multiple score functions
- [ ] GPU acceleration
- [ ] Reinforcement learning for α selection
- [ ] REST API client
- [ ] React hooks
- [ ] Vue composables

💬 Support

For issues, questions, or suggestions:

- Open an issue on GitHub
- Check documentation
- Review examples

---

Built with ❤️ for the quantitative trading and ML communities