Conformal prediction for neural trading with guaranteed intervals
npm install @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.
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
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.
- 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@neural-trader/neural
- 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
- Browser & Node.js: Works in browsers, Node.js, Electron, React Native
- TypeScript Support: Full type definitions, 100% type-safe
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
`๐ 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(
); // 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 exampleRun 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`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.
- Conformal Prediction Theory
- Adaptive Conformal Inference
- Conformalized Quantile Regression
- Repository
- Rust Crate
- [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
For issues, questions, or suggestions:
- Open an issue on GitHub
- Check documentation
- Review examples
---
Built with โค๏ธ for the quantitative trading and ML communities