Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.summand.com/llms.txt

Use this file to discover all available pages before exploring further.

The Forecast component projects future values for a single time-series target. It’s a two-piece chain:
  • forecast_model (internal) — fits a Holt-Winters / SES model on the aggregated history and persists the fit to S3.
  • forecast (user-visible) — pulls the cached fit, calls .forecast(steps=horizon), derives 95% prediction intervals, and emits the JSON the chat UI renders.
The split is deliberate: re-running with a different horizon shouldn’t refit the model. Statsmodels’ own docs are explicit on this — refit is for new observations, not for varying the projection horizon. Splitting the components lets the dispatcher cache the fit and only re-run the cheap projection step when only horizon changes.

​
Inputs

InputTypeRequiredDescription
date_columncolumn reference✓The timestamp column. Must parse as a date.
target_columncolumn reference✓The numeric column to project forward.
horizonintegeroptional (default 12)How many steps to forecast. Units depend on the inferred frequency (months, weeks, days, etc.).
The frequency is inferred from the spacing of date_column values — daily, weekly, monthly, quarterly. The component picks an appropriate seasonal period (12 for monthly, 7 for daily, etc.).

​
Output shape

{
  "frequency": "MS",
  "horizon": 12,
  "model": "Holt-Winters (additive seasonal, period=12)",
  "seasonality_period": 12,
  "rmse": 1842.5,
  "first_history_period": "2023-01-01",
  "last_history_period": "2026-04-01",
  "last_forecast_period": "2027-04-01",
  "series": [
    { "period": "2023-01-01", "value": 12450.0, "kind": "history" },
    { "period": "2023-02-01", "value": 13200.0, "kind": "history" },
    ...
    { "period": "2026-05-01", "value": 18900.0, "lower": 17050.0, "upper": 20750.0, "kind": "forecast" },
    { "period": "2026-06-01", "value": 19200.0, "lower": 17150.0, "upper": 21250.0, "kind": "forecast" },
    ...
  ]
}
The series array combines history and forecast — kind flags which is which, and lower / upper (the 95% interval) are present only on forecast points. The artifact lives at forecast.json.

​
Display

The Forecast component ships with a chart-block renderer:
  • Line chart of history + forecast in one series, with a shaded confidence band over the forecast portion.
  • Model details key/value block — frequency, seasonality period, RMSE.
  • Forecast table — per-period numeric output for copy-paste.

​
Filtering from chat

The full forecast artifact is small (history + horizon points), so chat usually reads it whole rather than filtering. Summand surfaces summary fields like rmse, last_history_period, and last_forecast_period for at-a-glance answers, with the full series available on demand.

​
Compute profile

ComponentProfileMemoryTimeout
forecast_modelLambda2 GB180 s
forecastLambda1 GB60 s
Both run on Lambda — Holt-Winters fits in seconds for typical historical lengths. There’s no Fargate path because the cost of a refit isn’t worth the parallelism.

​
Use cases

  • Revenue / cost projections — monthly forecasts with prediction intervals for budgeting.
  • Headcount / capacity planning — extending a weekly headcount series N weeks forward.
  • Operational metrics — daily request volume, latency, or error rate trended forward.

​
Common gotchas

Holt-Winters captures level, trend, and seasonality but not structural breaks or external shocks. If your series has a known regime change (e.g. major launch, pricing change), the forecast will smooth across it. Filter the source to a stable post-change window via a view, then point the experiment at the view.
Wide intervals mean the model has high residual variance — the historical series isn’t well-explained by level + trend + seasonal pattern. Either the data is genuinely volatile, or there’s missing structure (e.g. a covariate the model can’t see). Holt-Winters is univariate; if you need multivariate forecasting, that’s roadmap.
The inference looks at the spacing of date_column values. If your data has gaps or irregular cadence, frequency detection can pick the wrong period. Aggregating to a regular frequency in a view before the experiment usually fixes this.