@neural-trader/example-supply-chain-prediction

Self-learning demand forecasting and swarm-based inventory optimization with uncertainty quantification for retail, manufacturing, and e-commerce supply chains.

Features

Demand Forecasting

• Conformal Prediction: Guaranteed prediction intervals with statistical validity
• Seasonal Pattern Recognition: Automatic detection via AgentDB memory
• Trend Analysis: Linear and exponential trend modeling
• Multi-Horizon Forecasts: 1-day to 30-day predictions
• Online Learning: Continuous adaptation to new data
• Uncertainty Quantification: Lead time and demand uncertainty modeling

Inventory Optimization

• Multi-Echelon Networks: Optimize entire supply chain hierarchies
• Safety Stock Calculation: Statistical methods with lead time uncertainty
• Service Level Optimization: Target-based or adaptive service levels
• Cost Minimization: Balance holding, ordering, and shortage costs
• Dynamic Policies: (s,S), (R,s,S), and base-stock policies
• Flow Optimization: Coordinate replenishment across network

Swarm Intelligence

• Particle Swarm Optimization: Explore policy parameter space
• Multi-Objective: Balance cost and service level simultaneously
• Pareto Front: Discover trade-off solutions
• Adaptive Learning: Self-tune service level targets
• Parallel Evaluation: Fast policy exploration via agentic-flow

Installation

npm install @neural-trader/example-supply-chain-prediction

Dependencies

This package requires:

• @neural-trader/predictor - Conformal prediction engine
• agentdb - Vector memory for pattern storage
• agentic-flow - Multi-agent coordination
• openrouter - LLM-based disruption prediction (optional)

Quick Start

import { createSupplyChainSystem } from '@neural-trader/example-supply-chain-prediction';

// Create system
const system = createSupplyChainSystem();

// Add inventory nodes
system.addInventoryNode({
  nodeId: 'warehouse-1',
  type: 'warehouse',
  level: 1,
  upstreamNodes: ['supplier-1'],
  downstreamNodes: ['store-1', 'store-2'],
  position: { currentStock: 500, onOrder: 100, allocated: 50 },
  costs: { holding: 0.5, ordering: 100, shortage: 50 },
  leadTime: { mean: 7, stdDev: 2, distribution: 'normal' },
  capacity: { storage: 10000, throughput: 1000 },
});

// Train on historical data
await system.train(historicalDemand);

// Optimize inventory policies
const result = await system.optimize('product-123', {
  dayOfWeek: 1,
  weekOfYear: 20,
  monthOfYear: 5,
  isHoliday: false,
  promotions: 0,
  priceIndex: 1.0,
});

console.log('Best Policy:', result.bestPolicy);
console.log('Expected Cost:', result.networkOptimization.totalCost);
console.log('Service Level:', result.networkOptimization.avgServiceLevel);

Use Cases

Retail Supply Chain

import { retailExample } from '@neural-trader/example-supply-chain-prediction';

const result = await retailExample();

Features:

• Multi-location inventory management
• Seasonal demand patterns
• Promotional event planning
• Service level optimization for customer satisfaction

Manufacturing Supply Chain

import { manufacturingExample } from '@neural-trader/example-supply-chain-prediction';

const system = await manufacturingExample();

Features:

• Raw material inventory management
• Production line coordination
• High service level requirements (99%+)
• Very high shortage penalty costs

E-Commerce Supply Chain

import { ecommerceExample } from '@neural-trader/example-supply-chain-prediction';

const system = await ecommerceExample();

Features:

• Fulfillment center optimization
• Fast delivery requirements (1-2 day lead times)
• High demand variability
• Multi-channel coordination

Architecture

Demand Forecaster

DemandForecaster provides self-learning demand prediction:

import { DemandForecaster } from '@neural-trader/example-supply-chain-prediction';

const forecaster = new DemandForecaster({
  alpha: 0.1,                    // Confidence level (90%)
  horizons: [1, 7, 14, 30],      // Forecast horizons
  seasonalityPeriods: [7, 52],   // Weekly and yearly
  learningRate: 0.01,            // Online learning rate
  memoryNamespace: 'my-supply-chain',
});

// Train on historical patterns
await forecaster.train(historicalData);

// Generate forecast with uncertainty
const forecast = await forecaster.forecast(
  'product-123',
  currentFeatures,
  horizon
);

console.log('Point Forecast:', forecast.pointForecast);
console.log('95% Interval:', [forecast.lowerBound, forecast.upperBound]);
console.log('Uncertainty:', forecast.uncertainty);

Inventory Optimizer

InventoryOptimizer calculates optimal inventory policies:

import { InventoryOptimizer } from '@neural-trader/example-supply-chain-prediction';

const optimizer = new InventoryOptimizer(forecaster, {
  targetServiceLevel: 0.95,
  planningHorizon: 30,
  reviewPeriod: 7,
  safetyFactor: 1.65,
  costWeights: {
    holding: 1,
    ordering: 1,
    shortage: 5,
  },
});

// Add network nodes
optimizer.addNode(warehouseNode);
optimizer.addNode(storeNode);

// Optimize entire network
const optimization = await optimizer.optimizeNetwork(
  'product-123',
  currentFeatures
);

// Get (s,S) policy for each node
for (const result of optimization.nodeResults) {
  console.log(`${result.nodeId}:`);
  console.log(`  Reorder Point (s): ${result.reorderPoint}`);
  console.log(`  Order-Up-To (S): ${result.orderUpToLevel}`);
  console.log(`  Safety Stock: ${result.safetyStock}`);
}

Swarm Policy Optimizer

SwarmPolicyOptimizer uses particle swarm optimization to find best policies:

import { SwarmPolicyOptimizer } from '@neural-trader/example-supply-chain-prediction';

const swarmOptimizer = new SwarmPolicyOptimizer(forecaster, optimizer, {
  particles: 20,
  iterations: 50,
  inertia: 0.7,
  cognitive: 1.5,
  social: 1.5,
  bounds: {
    reorderPoint: [0, 1000],
    orderUpToLevel: [100, 2000],
    safetyFactor: [1.0, 3.0],
  },
  objectives: {
    costWeight: 0.6,
    serviceLevelWeight: 0.4,
  },
});

// Run swarm optimization
const result = await swarmOptimizer.optimize('product-123', currentFeatures);

console.log('Best Policy:', result.bestPolicy);
console.log('Convergence:', result.convergenceHistory);

// Get Pareto front for multi-objective analysis
const paretoFront = swarmOptimizer.getParetoFront();
for (const solution of paretoFront) {
  console.log(`Cost: ${solution.fitness.cost}, Service: ${solution.fitness.serviceLevel}`);
}

Advanced Features

Online Learning

The system continuously learns from new observations:

// Update with new demand observation
await system.update({
  productId: 'product-123',
  timestamp: Date.now(),
  demand: 150,
  features: currentFeatures,
});

Adaptive Service Levels

Automatically tune service level targets based on revenue goals:

const optimalServiceLevel = await swarmOptimizer.adaptServiceLevel(
  'product-123',
  currentFeatures,
  targetRevenue
);

console.log('Optimal Service Level:', optimalServiceLevel);

Real-Time Recommendations

Get actionable recommendations for inventory managers:

const recommendations = await system.getRecommendations(
  'product-123',
  currentFeatures
);

for (const rec of recommendations.recommendations) {
  console.log(`${rec.nodeId}: ${rec.action} ${rec.quantity} units (${rec.urgency})`);
  console.log(`Reason: ${rec.reason}`);
}

Performance Simulation

Simulate inventory performance over time:

const simulation = await optimizer.simulate(
  'product-123',
  currentFeatures,
  periods
);

console.log('Avg Service Level:', simulation.avgServiceLevel);
console.log('Avg Cost:', simulation.avgInventoryCost);
console.log('Stockouts:', simulation.stockouts);
console.log('Fill Rate:', simulation.fillRate);

Configuration

Forecast Configuration

const forecastConfig = {
  alpha: 0.1,                      // Confidence (1-alpha coverage)
  horizons: [1, 7, 14, 30],        // Forecast horizons in days
  seasonalityPeriods: [7, 52],     // Seasonal periods to detect
  learningRate: 0.01,              // Online learning rate (0-1)
  memoryNamespace: 'supply-chain', // AgentDB namespace
};

Optimizer Configuration

const optimizerConfig = {
  targetServiceLevel: 0.95,        // Target fill rate
  planningHorizon: 30,             // Planning horizon in days
  reviewPeriod: 7,                 // Review period in days
  safetyFactor: 1.65,              // Z-score for safety stock
  costWeights: {
    holding: 1,                    // Holding cost weight
    ordering: 1,                   // Ordering cost weight
    shortage: 5,                   // Shortage cost weight
  },
};

Swarm Configuration

const swarmConfig = {
  particles: 20,                   // Number of particles
  iterations: 50,                  // Optimization iterations
  inertia: 0.7,                    // Inertia weight (0-1)
  cognitive: 1.5,                  // Cognitive weight
  social: 1.5,                     // Social weight
  bounds: {
    reorderPoint: [0, 1000],       // Search bounds for s
    orderUpToLevel: [100, 2000],   // Search bounds for S
    safetyFactor: [1.0, 3.0],      // Search bounds for Z
  },
  objectives: {
    costWeight: 0.6,               // Weight for cost objective
    serviceLevelWeight: 0.4,       // Weight for service objective
  },
};

Examples

See the /examples directory for complete scenarios:

• retail-scenario.ts - Multi-location retail optimization
• (Add more examples as needed)

Run examples:

npm run dev examples/retail-scenario.ts

Testing

Run comprehensive test suite:

npm test

Run with coverage:

npm run test:coverage

Watch mode:

npm run test:watch

API Reference

Classes

• DemandForecaster - Self-learning demand forecasting
• InventoryOptimizer - Multi-echelon inventory optimization
• SwarmPolicyOptimizer - Swarm-based policy search
• SupplyChainSystem - Complete integrated system

Interfaces

• DemandPattern - Historical demand observation
• DemandForecast - Forecast with uncertainty
• InventoryNode - Network node definition
• OptimizationResult - Node optimization result
• PolicyParticle - Swarm particle

Factory Functions

• createSupplyChainSystem() - Create system with defaults
• retailExample() - Retail scenario example
• manufacturingExample() - Manufacturing scenario example
• ecommerceExample() - E-commerce scenario example

Performance

• Conformal Prediction: Statistical guarantees on prediction intervals
• Swarm Optimization: Parallel policy evaluation via agentic-flow
• AgentDB Memory: 150x faster vector search for pattern retrieval
• Online Learning: Real-time adaptation to changing demand

Contributing

Contributions welcome! Please read CONTRIBUTING.md for guidelines.

License

MIT License - see LICENSE for details.

Links

• Neural Trader Documentation
• @neural-trader/predictor
• AgentDB
• Agentic Flow

Citation

If you use this package in research, please cite:

@software{neural_trader_supply_chain,
  title = {Neural Trader Supply Chain Prediction},
  author = {Neural Trader Team},
  year = {2024},
  url = {https://github.com/ruvnet/neural-trader}
}