Forecast

When to useCopy Anchor Link

• The user asks where a business or personal metric is heading: next quarter's revenue, when the runway ends, how many support tickets to expect, whether a savings goal will be met.
• A forecasting tool returned the history and the model's median, ideally with quantile bands.

When not to useCopy Anchor Link

• You have no forecasting tool result. Never extrapolate a trend yourself or invent bands.
• The user wants to move the inputs and watch the outcome change. Use Simulation.
• It's a weather forecast. Use Weather.
• The user only asks about the past. Use a Chart.

How the agent should use itCopy Anchor Link

• Copy history, forecast, scenarios, drivers, method and accuracy from the tool result unchanged. They're all data-bound.
• Pass only the quantiles the model returned. p10/p90 draw the 80% range and p25/p75 the 50% range. Without them the chart shows the median alone, which is better than a made-up band.
• Use threshold for a limit the user fears crossing (cash at 0, capacity) and target for a goal. The component works out the crossing date itself, from the median and from the band edges, so don't put dates in the labels.
• Keep assumptionsNote to one sentence. When the assumptions matter to the answer, follow with the Assumptions component so the user can correct them.
• On adjust, show Assumptions or Preference Controls; on alert, confirm the alert before creating it. Re-run the forecast after any change and supersede the old card.
• Lifecycle: forecasts age. Set fetchedAt to the time the model ran and staleAfterMs to one period of the data (a day for daily data, a week for weekly), so the Renderer offers a refresh. When the forecast is re-run, mark the old call superseded. No expiresAt.

Reading the forecastCopy Anchor Link

• Headline. The median at the end of the horizon in large type ("$1.18M in Dec 2026") with the 80% range in words under it. When the median crosses a threshold, the crossing date leads instead ("~Aug 2027 Runway ends"). When the median reaches a target, a line names it ("Goal $1.2M ~Dec 2026"). The change against the last actual is read to screen readers; when the median ends on the other side of zero, it's an amount, not a percentage.
• Chart. Actuals are a solid line and the median a dashed line that continues from the last actual. The 80% range is the lighter band and the 50% range the darker one, both one chart color at low opacity. A vertical line marks today. One compact key row names the lines and bands.
• Crossings. Target and threshold lines are labeled. Where the median crosses one, a marker shows the date, found by linear interpolation between points (lines are drawn linearly too, so the marker sits on the line). The early and late dates from the 80% band edges, or the note that the median never gets there within the horizon, are read to screen readers.
• Scenarios. With scenarios, a Median / Scenarios switch replaces the median and bands with up to three scenario lines, told apart by dash pattern as well as shade. Scenario notes are read to screen readers.
• Drivers and assumptions. drivers, method, accuracy and assumptionsNote sit behind a collapsed "Drivers and assumptions" disclosure, so the card leads with the answer.

InteractionCopy Anchor Link

• Keyboard. The chart is focusable. Left and Right move between periods, starting at the last actual; Home and End jump to the ends and Escape clears. Each period's actual, or its median and ranges, is announced in a polite live region and shown in the tooltip.
• Actions. actions: ["adjust"] adds Change assumptions; "alert" adds Set an alert for the threshold. Each press sends a result and leaves a short note in the footer. The forecast never locks: they're handoffs, and the user may press both.

AccessibilityCopy Anchor Link

The chart's SVG is hidden from screen readers. The focusable chart is described by a summary of the forecast, a visually hidden table lists every period with its actual, median, both ranges and each scenario, and the crossing sentences are visually hidden text. Driver arrows have "Pushes up" or "Pushes down" in hidden text, so direction isn't carried by the icon alone.

InstallationCopy Anchor Link

npx shadcn@latest add https://your-site.com/r/forecast.json

UsageCopy Anchor Link

import { tool } from "ai"
import { forecastTool } from "@/components/genui/forecast.schema"

const tools = {
  [forecastTool.name]: tool({
    description: forecastTool.description,
    inputSchema: forecastTool.inputSchema,
  }),
}

Without actions the forecast is display-only, so give the tool an execute that returns immediately. With them, the agent receives:

{ action: "adjust" }
{ action: "alert", value: 0 }

Render it through the Renderer under show_forecast, or directly:

<Forecast
  {...part.input}
  status={part.state === "input-streaming" ? "streaming" : undefined}
  result={part.state === "output-available" ? part.output : undefined}
  onResult={(result) => {
    if (part.state !== "output-available") {
      addToolResult({ tool: "show_forecast", toolCallId: part.toolCallId, output: result })
    } else {
      sendMessage({ text: `Forecast action: ${JSON.stringify(result)}` })
    }
  }}
/>

While streaming, the header shows placeholders, the chart appears once there's history and at least two forecast points, and the drivers arrive last. The headline and crossing dates wait for the finished forecast, so they never jump.

With LangGraphCopy Anchor Link

Push it from a graph node with ui.push({ name: "show_forecast", props: { toolCallId, ...args } }, { message }), and render the thread's UI messages with the Renderer.

Restoring from historyCopy Anchor Link

Pass the stored result back as result, or an array when the user took both actions. The notes show in the footer and onResult isn't called. The buttons stay available, since actions are handoffs.

<Forecast {...part.input} result={part.state === "output-available" ? part.output : undefined} />

SchemaCopy Anchor Link

Host props: status (streaming or ready), onResult, result and className.

SourceCopy Anchor Link