@sipemu/anofox-forecast 0.4.5 → 0.4.6

package/README.md

@@ -116,6 +116,17 @@ const ts = TimeSeries.withTimestamps(
 | `AutoForecaster` | Best of ARIMA, ETS, Theta | - |
 | `AutoEnsembleForecaster` | Ensemble of top-K models | - |
 
+### Orchestration
+
+| Type | Description |
+|------|-------------|
+| `JsDataProfile` | Automated data profiling (stationarity, trend, quality) |
+| `JsPipelineBuilder` | Declarative pipeline construction |
+| `JsPipelineResult` | Pipeline result with forecast and diagnostics |
+| `JsPipelineReport` | Structured multi-section report |
+| `selectModels()` | Model recommendation from data profile |
+| `explainResult()` | Human-readable result explanation |
+
 ## Prediction Intervals
 
 Most models support prediction intervals:
@@ -225,6 +236,121 @@ const pi = processor.predictIntervals(trained, newForecasts);
 - `JsPostProcessor` — unified API wrapping all methods
 - `JsBacktestConfig` / `JsBacktestResult` — rolling/expanding window backtesting
 
+## Orchestration / Agent Forecasting
+
+Build autonomous forecasting pipelines with data profiling, multi-metric model selection, preprocessing, ensemble construction, and structured reporting:
+
+### Data Profiling
+
+```javascript
+import { JsDataProfile } from '@sipemu/anofox-forecast';
+
+// Profile a time series
+const profile = JsDataProfile.fromSeries(ts);
+console.log('Observations:', profile.nObservations);
+console.log('Trend:', profile.trendDirection);      // "Rising", "Falling", "Flat"
+console.log('Stationary?', profile.isStationary);
+console.log('Intermittent?', profile.isIntermittent);
+console.log('Quality:', profile.qualityScore);       // 0.0 to 1.0
+
+// Full profile as JSON
+const json = profile.toJSON();
+
+// Profile raw values (no timestamps needed)
+const profile2 = JsDataProfile.fromValues(new Float64Array([1, 2, 3, 4, 5]));
+```
+
+### Model Selection
+
+```javascript
+import { JsDataProfile, selectModels } from '@sipemu/anofox-forecast';
+
+const profile = JsDataProfile.fromSeries(ts);
+
+// Get model recommendations based on data characteristics
+const result = selectModels(profile);
+console.log('Recommended:', result.recommended);  // ["ARIMA", "ETS", "Naive", "SES"]
+console.log('Reasoning:', result.reasoning);       // ["High autocorrelation...", ...]
+
+// Filter to available models
+const filtered = selectModels(profile, ["Naive", "SES", "ARIMA"]);
+```
+
+### Pipeline Builder
+
+```javascript
+import { JsPipelineBuilder } from '@sipemu/anofox-forecast';
+
+// Build and execute a forecasting pipeline
+const result = new JsPipelineBuilder()
+  .profile()                 // enable data profiling
+  .preprocess('auto')        // auto Box-Cox + outlier treatment
+  .metric('auto')            // data-aware metric selection
+  .ensemble('auto')          // ensemble if MCS includes > 1 model
+  .addModel('Naive')
+  .addModel('SES')
+  .addModel('SMA')
+  .withFallback()            // Naive → SMA fallback chain
+  .nonNegative()             // clamp forecasts >= 0
+  .execute(ts, 12);          // 12-step forecast
+
+console.log('Model:', result.modelName);
+console.log('Forecast:', result.forecast.values);
+console.log('Decision log:', result.decisionLog);
+
+// Access diagnostics
+const profile = result.profile;            // JsDataProfile or undefined
+const mcs = result.modelConfidenceSet;     // { included, pValue, singleWinner }
+const scores = result.metricScores;        // [{ model, score, components }]
+const weights = result.ensembleWeights;    // [{ model, weight }] or undefined
+const preprocess = result.preprocessInfo;  // { boxcoxLambda, outliersReplaced, stepsApplied }
+```
+
+#### Builder Options
+
+| Method | Options | Description |
+|--------|---------|-------------|
+| `profile()` | — | Enable data profiling |
+| `preprocess(mode)` | `"auto"`, `"none"` | Preprocessing (Box-Cox, outlier replacement) |
+| `metric(strategy)` | `"auto"`, `"mae"`, `"mse"`, `"rmse"`, `"smape"`, `"wape"`, `"mda"` | Metric for model ranking |
+| `ensemble(mode)` | `"auto"`, `"none"`, `"mean"`, `"median"`, `"weighted"` | Ensemble construction |
+| `addModel(name)` | `"Naive"`, `"SES"`, `"SMA"`, `"SMA3"`, `"SMA5"`, `"SMA10"`, `"SeasonalNaive"` | Register a model |
+| `addSeasonalModel(name, period)` | — | Register a seasonal model |
+| `selectModels(k)` | — | Select top-K models |
+| `crossValidate(folds, horizon)` | — | Enable cross-validation |
+| `withFallback()` | — | Enable fallback chain |
+| `nonNegative()` | — | Clamp forecasts to non-negative |
+| `seasonalPeriod(p)` | — | Set seasonal period hint |
+
+### Pipeline Report
+
+```javascript
+// Generate a structured report
+const report = result.report();
+console.log(report.title);             // "Pipeline Report: SES"
+console.log(report.sectionCount);      // number of sections
+console.log(report.toString());        // full formatted text
+
+// Report as JSON with typed sections
+const json = report.toJSON();
+// { title, sections: [{ heading, content: { type, ... } }] }
+// Content types: "text", "keyValue" (with pairs), "table" (with headers + rows)
+```
+
+### Explain Result
+
+```javascript
+import { explainResult } from '@sipemu/anofox-forecast';
+
+// Generate a human-readable explanation
+const brief = explainResult(result, 'brief');
+console.log(brief.summary);  // "Selected SES for 12-step forecast."
+
+const detailed = explainResult(result, 'detailed');
+console.log(detailed.summary);
+detailed.sections.forEach(s => console.log(s.heading, s.content));
+```
+
 ## Calendar Annotations
 
 Add holidays and named regressors for models that support exogenous variables:
@@ -281,8 +407,8 @@ const forecast = model.predict(10);
 ## Limitations
 
 - The `parallel` feature from the Rust crate is not available in WASM
-- Postprocessing features (conformal prediction, IDR) are not yet exposed
-- Cross-validation utilities are not yet exposed
+- IDR (Isotonic Distributional Regression) and QRA are not yet exposed in WASM
+- Abstract storage (`PipelineStore`) is not exposed — use the report JSON output for persistence
 
 ## License