Forecaster Tool

The Forecaster tool builds predictive models for time series data, helping you anticipate future values based on historical patterns. It’s designed for business forecasting scenarios like demand planning, revenue projections, and inventory management.

What the Forecaster Does

The Forecaster analyzes your historical data and generates predictions with confidence intervals. It automatically selects the best forecasting method (ARIMA, ARIMAX, or Prophet) based on your data characteristics.

Key capabilities:

• Predict future values for any numeric metric over time
• Generate confidence intervals showing the range of likely outcomes
• Forecast multiple series at once (e.g., per product, per region)
• Handle seasonality automatically when patterns exist in your data
• Create visualizations showing historical data alongside predictions

Forecasting vs. Classification

Use the Forecaster when you want to predict future numeric values over time (revenue next quarter, demand next month). Use the Researcher when you want to classify or categorize data (industry labels, sentiment scores).

When to Use It

Scenario	Example
Revenue projections	”Forecast monthly revenue through year-end”
Demand planning	”Predict units sold per product for next 12 weeks”
Inventory management	”Project stock levels by warehouse”
Traffic forecasting	”Forecast daily website visitors for next month”
Capacity planning	”Predict server load for next quarter”

When NOT to Use It

The Forecaster isn’t the right tool when:

• Data isn’t time-based — no dates or timestamps to forecast against
• Too little history — fewer than 20 data points won’t produce reliable forecasts
• You need classification — use the Researcher for categorization tasks
• One-time calculations — forecasting is for projecting trends, not single computations

How to Prompt for Forecasts

Simply describe what you want to predict and for how long. The agent recognizes forecasting requests and automatically invokes the Forecaster tool.

Effective Prompts

Basic forecasting:

• “Forecast revenue for the next 3 months”
• “Predict customer growth through year-end”
• “Project sales for the next 12 weeks”

With time frame specification:

• “Forecast demand for the next 6 months”
• “Predict inventory levels through Q4”
• “Project website traffic for the next 30 days”

Multiple series forecasting:

• “Forecast sales for each product category”
• “Predict demand by region for the next quarter”
• “Project revenue per customer segment through December”

Default Forecast Period

If you don’t specify a time frame, the Forecaster defaults to 16 weeks ahead. You can always request a different period:

"Forecast revenue for the next 3 months"
"Predict demand through the end of 2024"
"Project the next 52 weeks of sales"

Understanding Your Results

The Output DataFrame

When the Forecaster runs, it creates an updated_df with both your original data and predictions:

Column	Description
Your date column	Time periods (original + future)
Your value column	Actual values (historical) and predicted values (future)
value_type	”observed” for historical, “predicted” for forecasts
{column}_lower_estimate	Lower bound of confidence interval
{column}_upper_estimate	Upper bound of confidence interval

Example output:

month	revenue	value_type	revenue_lower_estimate	revenue_upper_estimate
2024-01	50000	observed	—	—
2024-02	52000	observed	—	—
2024-03	55000	predicted	51000	59000
2024-04	58000	predicted	52000	64000

Reading the Visualization

The Forecaster automatically creates a chart showing:

• Solid line: Historical (observed) data
• Dashed line: Predicted values
• Shaded area: Confidence interval (the range where actual values are likely to fall)

The wider the shaded area, the more uncertainty in the prediction. Confidence intervals typically widen as you forecast further into the future.

Preparing Your Data for Best Results

Data Requirements

For reliable forecasts, your data should have:

1. A time column — dates, timestamps, weeks, months, or quarters
2. A numeric value to forecast — revenue, units, visitors, etc.
3. At least 20 data points — more history generally means better predictions
4. Consistent time intervals — weekly data, monthly data, etc. (gaps are okay but should be minimal)

Recommended Data Preparation

Aggregate before forecasting:

"Aggregate to weekly totals, then forecast for the next 12 weeks"

Handle missing periods:

"Fill missing dates with zeros, then forecast revenue"

Group by category first:

"Group sales by product, then forecast each product separately"

How Much History Do You Need?

Forecast Type	Minimum History	Recommended
Simple trends	20 data points	50+ points
Weekly seasonality	4 weeks	12+ weeks
Monthly seasonality	12 months	24+ months
Yearly seasonality	2 years	3+ years

More history helps the model identify patterns and produce tighter confidence intervals.

Tips for Better Forecasts

Handling Seasonality

If your data has seasonal patterns (holiday spikes, summer slowdowns, etc.), the Forecaster can detect and incorporate them—but only if you have enough history:

• Weekly patterns: Need 4+ weeks of daily data
• Monthly patterns: Need 12+ months of data
• Yearly patterns: Need 2+ years of data

"Forecast monthly sales, accounting for seasonal patterns"

Forecasting Multiple Categories

You can forecast many series at once by specifying groupings:

"Forecast demand for each product over the next 8 weeks"
"Predict revenue by region through Q4"
"Project sales per salesperson for the next month"

The Forecaster will build separate models for each category and return results for all of them.

When Forecasts Look Flat

If your forecast shows a flat line with no trend:

• Your historical data may not have a clear trend
• Try aggregating to a coarser time grain (daily → weekly → monthly)
• Check if there’s enough variation in your data

When Confidence Intervals Are Wide

Wide confidence intervals indicate uncertainty. This happens when:

• You have limited historical data
• Your data has high volatility
• You’re forecasting far into the future

To narrow intervals:

• Add more historical data
• Aggregate to reduce noise
• Forecast shorter time periods

Real-World Examples

Example 1: Monthly Revenue Forecasting

Starting data: 24 months of monthly revenue

Step 1: Check your data

"Show me monthly revenue for the past 2 years"

Step 2: Generate forecast

"Forecast monthly revenue for the next 6 months with confidence intervals"

Step 3: Visualize

"Create a line chart showing historical and forecasted revenue"

Example 2: Demand Forecasting by Product

Starting data: Weekly sales by product

Step 1: Prepare data

"Aggregate to weekly totals by product"

Step 2: Forecast

"Forecast demand for each product for the next 12 weeks"

Step 3: Focus on top products

"Show the forecast chart for the top 5 products by volume"

Example 3: Inventory Planning

Starting data: Daily stock levels by warehouse

Step 1: Aggregate

"Calculate weekly average stock levels by warehouse"

Step 2: Forecast

"Predict stock levels for each warehouse over the next 8 weeks"

Step 3: Identify risks

"Show warehouses where predicted stock falls below 100 units"

Troubleshooting

”Not enough data to perform forecasting”

Cause: Fewer than 20 data points for a series.

Fix:

• Add more historical data
• Aggregate to fewer, larger time periods (daily → weekly)
• Remove category groupings to forecast the total instead

”Forecast values seem unrealistic”

Cause: Outliers or data quality issues in historical data.

Fix:

• Check for and remove outliers: “Remove months where revenue was zero”
• Verify data is clean: “Show me any unusual values in the revenue column”
• Use a shorter forecast horizon

”Model failed to converge”

Cause: Data patterns too complex or inconsistent for the model.

Fix:

• Simplify by aggregating: “Convert to monthly totals first”
• Remove problematic series: “Exclude products with fewer than 20 weeks of data”
• Try a different time grain

”Confidence intervals are extremely wide”

Cause: High volatility or insufficient history.

Fix:

• Add more historical data if available
• Aggregate to smooth out noise
• Accept that some forecasts are inherently uncertain

Forecasting Best Practices

1. Start with exploration — understand your data before forecasting
2. Aggregate appropriately — daily data often needs to become weekly or monthly
3. Check for outliers — unusual values can skew predictions
4. Validate with holdout — if possible, test on recent data you already have
5. Update regularly — refresh forecasts as new data arrives
6. Communicate uncertainty — always show confidence intervals to stakeholders

Next Steps

• Researcher Tool — for classification instead of prediction
• Working with Dates — prepare time series data
• Aggregating Data — summarize before forecasting
• Creating Visualizations — customize forecast charts
• Dashboard Basics — add forecasts to dashboards