Spoke

forecasting

Decision theory as service APIs — , / , aligned-chance trees.

Character

A PA professional supporting decisions — org redesigns, RIF analyses, "should we do the study" calls, strategic workforce planning. You know Monte Carlo and VOI exist; you'd never get budget for a specialized decision-analysis tool.

Problem

External. People decisions get made on gut feel, dressed up with bar charts. The few decision-analysis tools that exist (Lumina, @RISK, etc.) live in finance, not HR. They're priced for finance.

Internal. You're often the one in the meeting who knows the decision is bigger than the analysis. You can't model the uncertainty. The decision happens anyway.

Philosophical. Decision theory — Monte Carlo simulation, Value of Information (EVPI / EVSI), aligned-chance decision trees — has textbook solutions. It should be table stakes for analytical decision support.

Guide

Forecasting answers two questions every leadership team punts on: "given the uncertainty, what's the expected outcome of each option?" and "is the study we're about to commission actually worth running?" It does both with textbook decision-theory math wrapped behind a callable API. forecasting — Monte Carlo + VOI / EVPI / EVSI as callable service APIs. Seeded reproducible draws. Closed-form expression evaluation over named distributions. Aligned-chance decision-tree rollback for shared discrete uncertainty.

Abstract

Background. Workforce transformation and research bets consume multimillion-dollar budgets yet rarely expose decision-analysis rigor comparable to capital projects—inviting preventable regret and misplaced study commissioning.

Methodology. Alternatives enumerate chance forks with aligned probabilities across options. Monte Carlo emits seeded draws across canonical distributions plus empirical masses; payoff expressions evaluate algebraically inside the simulator. EVPI / EVSI routes combine baseline expectation, perfect-information ceilings, and aligned-chance tree reductions so shared uncertainties stay coherent.

Scope. Probabilistic layer only—finance NPV detail and statutory compliance integrate via sibling spokes (calculus, wage-compliance).

Contribution. Stateless MCP + HTTP contracts let CI/CD and conversational agents probe study value before spend commits.

Evidence / Provenance. Raiffa–Schlaifer VOI lineage cited in forecasting PAT memos with regression suites guarding numeric stability inside contracts/types.ts-driven handlers.

Plan

  1. 01

    Define a decision model

    forecasting.decision-models.create persists a decision tree: alternatives, chance nodes, outcomes.

  2. 02

    Run a Monte Carlo simulation

    forecasting.monte-carlo.run — seeded reproducible draws over named distributions (Normal, Lognormal, Triangular, Uniform, Beta, Discrete-empirical), closed-form expression evaluation.

  3. 03

    Compute VOI

    forecasting.voi.compute returns baseline EV, perfect-information EV, EVPI, and discrete EVSI on aligned-chance trees. The number that tells you whether the study is worth $200K before you commission it.

Call to Action

Direct. Try the API. Run a simulation free.

Transitional. Read the VOI methodology (Phase 3). See the live demo at /decision-wizard.

Spoke I/O (visual language v1)

Every toolbox spoke shares the same abstract choreography: typed inputs on the left, distilled verbs in the center, typed outputs on the right, and (when relevant) cross-spoke HTTP composition along the bottom rail. Source package: @people-analytics-toolbox/spoke-illustrations.

ForecastingINPUTSMAIN ACTIONSOUTPUTSHistorical series packMetricSeriesPackHorizon + scenario knobsForecastConfigFit forecasting modelSimulate intervalsProjections + intervalsForecastRibbonScenario tableStressPath[]COMPOSES WITHcalculusmetrics-catalog

Try it now

Copy this curl. Paste in any terminal. POST endpoint — set TOOLBOX_SERVICE_KEY in your shell first.

forecasting.voi.compute

POST

SERVICE KEY REQUIRED

Compute baseline EV, perfect-information EV, EVPI on an aligned-chance decision tree. Alternatives share a sharedUncertaintyId; branch probabilities are aligned.

curl -sS -X POST "https://people-analytics-toolbox.vercel.app/api/spokes/forecasting/voi/compute" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOOLBOX_SERVICE_KEY" \
  -d '{
  "tenantId": "demo-tenant",
  "alternatives": [
    {
      "id": "ship-now",
      "branches": [
        { "sharedUncertaintyId": "market", "branchId": "good", "probability": 0.6, "outcomeValue": 100 },
        { "sharedUncertaintyId": "market", "branchId": "bad", "probability": 0.4, "outcomeValue": -20 }
      ]
    },
    {
      "id": "wait",
      "branches": [
        { "sharedUncertaintyId": "market", "branchId": "good", "probability": 0.6, "outcomeValue": 80 },
        { "sharedUncertaintyId": "market", "branchId": "bad", "probability": 0.4, "outcomeValue": 30 }
      ]
    }
  ]
}'

Vendor the contract

The Zod contract is the source of truth. Vendor a copy into your consumer app — you keep it; we don't break it underneath you. Re-vendor when the version bumps.

// In your consumer app:
import { z } from "zod";

// Vendor a copy of these contracts from the toolbox repo at:
//   src/spokes/forecasting/contracts/types.ts

import {
  MonteCarloSpecSchema,
  MonteCarloRunResponseSchema,
  RegisterDecisionModelRequestSchema,
  DecisionModelRecordSchema,
  VOIComputeRequestSchema,
  VOIComputeResponseSchema,
  CONTRACT_VERSION,
} from "./vendored/forecasting/types";

// Then call the toolbox over HTTP or MCP.
// See docs/EXTERNAL-CONSUMERS.md for onboarding.

Source path: src/spokes/forecasting/contracts/types.ts · GitHub

Try in Dev ConsoleRead the explainerSee the K–T + VOI flow on /decision-wizardForecasting cards on /feedBack to all spokes

Failure

Another bad org change made without modeling. Another study commissioned that wouldn't change any decision regardless of outcome.

Success

Defensible decision support. "Is this study worth the spend" answered analytically. People decisions modeled with the rigor finance decisions get.