Forecast

beliefs.forecast.predict(actions) runs the engine's predictive model forward from the current state under each candidate action and reports an expected-value summary. Use it when you have a list of actions the agent could take and want to know which one is most likely to advance its understanding.

For move-related forecasts (operating on the engine's recommended moves), use beliefs.moves.forecast and beliefs.moves.cascade.

`beliefs.forecast.predict(actions, options?)`

1const forecasts = await beliefs.forecast.predict(
2  ['gather_evidence_apac', 'design_test_market_size', 'reframe_question'],
3  { horizon: 3, rollouts: 50 },
4)
5
6const ranked = [...forecasts].sort((a, b) => b.score - a.score)
7console.log(`Best action: ${ranked[0].summary} (score=${ranked[0].score})`)

The engine returns one summary per input action, in input order. You can zip back to your action list directly.

Options:

Option	Default	What it does
`horizon`	`1`	Rollout depth per action (max 5).
`rollouts`	`30`	Independent rollouts per action (max 200).
`maxTopics`	—	Cap on belief topics surfaced in `willAnswer`.
`agentId`	bound agent	Run the forecast as a different agent.
`signal`	—	`AbortSignal` for cancellation.

`ForecastSummary`

1{
2  id: string
3  summary: string
4  /** 0–1 expected value. Higher = more useful. */
5  score: number
6  /** Plain-English belief topics most likely to sharpen under this action. */
7  willAnswer: string[]
8  /** Confidence in the forecast itself, not the action. */
9  confidence: 'low' | 'medium' | 'high'
10  /** Short human explanation. */
11  why: string
12  suggestion?: string
13  relatedBeliefs?: string[]
14  internals?: { rollouts?, depth?, evidence?, expectedEntropyReduction? }
15}

confidence reflects how much evidence the predictive model has accumulated for the proposed action — distinct from score. A high-score action with confidence: 'low' means "this looks great, but we haven't seen this action before."

Cold-start behavior

On a fresh workspace with no archived deltas, every forecast comes back with confidence: 'low' and a low score. That's the honest answer — the model has no evidence yet. After a handful of after() calls, the predictive model starts producing meaningful forecasts.

Auth

Requires apiKey or scopeToken auth. See Auth.

beliefs.forecast.predict(actions, options?)

1const forecasts = await beliefs.forecast.predict(
2  ['gather_evidence_apac', 'design_test_market_size', 'reframe_question'],
3  { horizon: 3, rollouts: 50 },
4)
5
6const ranked = [...forecasts].sort((a, b) => b.score - a.score)
7console.log(`Best action: ${ranked[0].summary} (score=${ranked[0].score})`)

The engine returns one summary per input action, in input order. You can zip back to your action list directly.

Options:

Option

Default

What it does

horizon

1

Rollout depth per action (max 5).

rollouts

30

Independent rollouts per action (max 200).

maxTopics

—

Cap on belief topics surfaced in willAnswer.

agentId

bound agent

Run the forecast as a different agent.

signal

—

AbortSignal for cancellation.

ForecastSummary

1{
2  id: string
3  summary: string
4  /** 0–1 expected value. Higher = more useful. */
5  score: number
6  /** Plain-English belief topics most likely to sharpen under this action. */
7  willAnswer: string[]
8  /** Confidence in the forecast itself, not the action. */
9  confidence: 'low' | 'medium' | 'high'
10  /** Short human explanation. */
11  why: string
12  suggestion?: string
13  relatedBeliefs?: string[]
14  internals?: { rollouts?, depth?, evidence?, expectedEntropyReduction? }
15}

Cold-start behavior

Auth

Requires apiKey or scopeToken auth. See Auth.