Help Guide

🚀 Getting Started

SKU Forecaster helps you predict future demand for your products using advanced time series forecasting. Here's how to get started:

1. Load your data - Upload a CSV/Excel file or connect to a database using Pipelines
2. Map your columns - Tell the app which columns contain SKU IDs, dates, and values
3. Select SKUs - Choose which products to forecast (or select all)
4. Run forecast - Click "Run Forecast" and select your preferred model
5. Review & export - Analyze results, compare models, and export to CSV

🔌 Data Sources & Pipelines

Pipelines let you connect to external data sources and automatically refresh your forecasts. Create a pipeline once, run it anytime.

Supported Connectors

Creating a Pipeline

1. Click + New Pipeline in the sidebar
2. Select your data source type
3. Enter connection details (host, credentials, etc.)
4. Click Test Connection to verify
5. Preview data and map columns
6. Save the pipeline for future use

Custom SQL Queries

All database connectors support custom SQL queries. Use this to:

• Filter data by date range
• Join multiple tables
• Aggregate data at different levels
• Apply business logic before forecasting

SELECT 
    product_id as sku,
    sale_date as date,
    SUM(quantity) as value
FROM sales
WHERE sale_date >= '2023-01-01'
GROUP BY product_id, sale_date

📈 Running Forecasts

Basic Forecasting

1. Load your data (file upload or pipeline)
2. Select SKUs from the list (or click "Select All")
3. Set Forecast Horizon (number of periods to predict)
4. Choose a forecasting model (or use Auto)
5. Click Run Forecast

Column Mapping

For accurate forecasts, map these columns correctly:

Forecast Options

• Horizon: Number of future periods (default: 12)
• Model: Forecasting algorithm (Auto recommended)
• Confidence: Prediction intervals shown on charts

🧮 Forecasting Models

The app includes multiple forecasting methods. Use Auto to let the system choose the best model for each SKU.

Model Selection Tips

• Short history (<24 periods): Use ETS or Simple Average
• Seasonal patterns: Use ETS, Prophet, or Auto
• Intermittent demand: Use Croston, SBA, or TSB
• Have event / price data: Use Auto with covariates enabled — the tree models pick up the signal and Auto picks the best fit per SKU
• Need component-level explainability: Use Centrifuge (returns level / seasonal / ML weights)
• Not sure: Use Auto - it analyzes your data and picks the best per SKU

📦 Large Datasets

The app handles datasets with millions of rows and thousands of SKUs efficiently.

Large Dataset Features

• Automatic detection: Datasets over 5M rows trigger large dataset mode
• Background processing: Forecasts run as background jobs
• Parallel workers: Multiple CPUs used for faster processing
• Progress tracking: Real-time updates on job progress
• Batch processing: SKUs processed in efficient batches

SKU Selection Options

Background Jobs

For large forecasts, jobs run in the background:

1. Configure your forecast settings
2. Click Start Background Job
3. Monitor progress in the Jobs panel
4. Results auto-save when complete
5. Download or view results anytime

🆕 New Product Forecasting

Forecast demand for SKUs with no sales history. skuf.ai offers three complementary approaches in the purple New Product Mode panel — pick by what data you have and what question you need answered.

Step 1 — Define attributes

Open New Product Mode → set the new SKU's attributes (category, subcategory, color, brand, price, etc.). The dropdowns pull from your active dataset, so only values actually present in your catalog appear. The badge counter shows how many attributes you've set.

Step 2 — Pick your method

🔍 Analog Blend (Find Similar SKUs)

Find historical SKUs that resemble your new one, then weighted-average their forecasts. A toggle above the button lets you pick how analogs get chosen:

After analogs are returned, adjust the selected set (the top 5 by score are picked by default), then click Run Forecast. Result is a weekly forecast for the new SKU, blended from analog histories.

🧠 Attribute-Based Launch Model

A Ridge + Random Forest ensemble regression trained on every historical SKU's attributes → first-period sales volume. Predicts a single launch volume for the new item directly from its attributes — no analog matching needed.

• Output: predicted first-period volume + 80% prediction interval, implied total life volume, feature importances, R² of the fit.
• Needs: ≥3 historical SKUs to train (≥20 to engage Random Forest; Ridge always runs).
• Best when: the new SKU's attributes are well-represented in training and you want a quick number with a defensible CI rather than a weekly curve.
• Pairs with Sell-Through: the modal has an "Auto-Fill Sell-Through" button that pipes implied_total_life into the decay-curve panel to convert the point estimate into a weekly schedule.

📅 Seasonal Component Forecast

Match the new SKU's attributes to a 52-week profile in your seasonality library, then multiply by a Base Sales Rate (BSR) the library carries from analog historical SKUs. Best when you have a strong matching profile and trust the analog calibration. See the methodology page section 4 (BSR) and section 5 (Seasonality library) for the math.

Common attribute columns

• Category / Subcategory
• Price point / Price tier
• Brand
• Size / Pack size
• Color / Style
• Channel (online, retail, wholesale)
• Region / Market

📊 Covariates & External Data

Improve forecast accuracy by feeding skuf.ai the upstream signals that drive demand. The platform supports two distinct paths:

Path A — Auto-built event + price covariates (recommended)

When you create planning events and your dataset has a price column, skuf.ai can automatically build a per-SKU exogenous matrix and pass it to the tree-based models in Auto's leaderboard (Random Forest, Gradient Boost, LightGBM) at fit time. Set useExogenousCovariates: true on the job config and the system handles the rest:

• One indicator column per active event type (has_holiday, has_promotion, has_other) — set to 1 in weeks the event covers, 0 otherwise.
• One column for log price (when available).
• Both historical weeks AND forecast-horizon weeks get rows, so the tree models predict the effect on the holdout (real MAPE improvement) AND on future weeks.

Path B — Custom column covariates (advanced)

For exogenous signals beyond events and price (weather, marketing spend, macro indicators), include them as columns in your data file and select them in the Covariates tab.

1. Include covariate columns in your data file
2. Open the Covariates tab
3. Select which columns to use
4. Set lag values if needed (e.g., price effect delayed 1 period)
5. Run forecast — covariates auto-included for the models that support them

Which models use covariates

• Random Forest, Gradient Boost, LightGBM — consume exogenous columns alongside autoregressive lag features.
• Centrifuge with RF / GB in its ML slot — same matrix flows in.
• SARIMAX, Prophet — natively support exog (additional wiring planned).
• ETS, ARIMA, Croston, SBA, TSB, simple, trend — state-space or sparse-demand models, no exog by design.

🤖 AI Features

AI-powered features help you understand your data and get actionable insights.

AI Insights

Get natural language explanations of your forecast results:

• Why a forecast is trending up or down
• Key patterns and seasonality detected
• Anomalies and outliers flagged
• Recommendations for improvement

Dataset Intelligence

Automatic analysis of your data quality and patterns:

• Data completeness checks
• Outlier detection
• Seasonality analysis
• SKU classification (smooth, intermittent, lumpy)
• Relationship mapping between SKUs

AI Agent

Natural language interface to run complex analyses:

"Forecast the top 50 SKUs by volume for the next 6 months"
"Find products with declining sales trends"
"Compare ETS vs ARIMA accuracy for seasonal items"

📋 Results & Export

Understanding Results

Each forecast result includes:

• Point forecast: Expected value for each period
• Confidence intervals: Upper and lower bounds (typically 80%)
• Model used: Which algorithm generated the forecast
• Accuracy metrics: MAPE, MAE, RMSE from backtesting

Forecast Accuracy (MAPE)

Export Options

Saved Results

Access previous forecasts from the sidebar under "Forecast History". Each saved result includes:

• Full forecast data
• Model configuration used
• Timestamp and metadata
• Quick re-run capability

🔧 Troubleshooting

Common Issues

Getting Help

• Check server logs: npm run dev shows detailed errors
• Browser console: Press F12 → Console tab for frontend errors
• Test endpoints: Use the test suite npm test

Performance Tips

• Use Top N selection for initial testing
• Filter data in SQL queries before loading
• Install statsmodels for faster, more accurate models
• Use background jobs for 1000+ SKUs
• Enable parallel workers (automatic on multi-core systems)