World Model Interface

The World Model isn’t just a set of numbers — it’s a graph: metrics connected to the drivers that move them, the components they’re built from, and (soon) the actions that change them. The @oxy-hq/sdk World Model interface exposes that graph to a customer app so you can build experiences that let people navigate their business, not just read a dashboard.

Alpha. The node interface below — useWorldModel() and the expand / drivers / explain / size / drill verbs — ships today and is backed by the metric-tree analyses. It is a design preview and may still change. drill is intentionally limited (see below); action simulation is not yet built (see Simulate an action).

The node paradigm

Everything in the World Model is a node, and every node speaks the same verbs. Learn them once and they compose across the whole surface: render a node, let the user pick a verb, get more nodes back, recurse.

Verb	What it does	Returns
`expand`	Reveal one hop of relationships — a metric’s components and drivers.	more nodes
`drivers`	Rank the declared drivers of a metric by influence.	a sensitivity list
`explain`	Root-cause a period-over-period move: why it dropped or climbed.	a driver/segment breakdown
`size`	Compare a node to its peers and size the gap.	ranked opportunities
`drill`	Narrow into a segment or entity instance.	a scoped node

Get the interface

A single hook — useWorldModel — returns the whole interface, scoped to the customer app’s project. It must run inside an OxyAppProvider. Everything else hangs off it: grab a node with metric(id) and the node speaks the verbs.

import { useWorldModel } from "@oxy-hq/sdk";

function Explorer() {
  const world = useWorldModel();

  // The graph, rooted anywhere you like.
  const tree = await world.tree("orders.net_revenue");
  // tree.nodes: MetricNode[]  — id, label, measure, is_composite, expr
  // tree.edges: MetricEdge[]  — from, to, kind: "component" | "driver",
  //                             direction, strength, confidence, form

  // Or focus a single node and carry it around — every verb is a method on it.
  const revenue = world.metric("orders.net_revenue");
  const node = await revenue.node(); // the measure itself (label, expr, is_composite)
}

world.metric(id) returns a handle. Each verb is an async method on the handle, so you can nest them into a click-to-open UI.

Expand into components and drivers

expand fetches one hop of the tree on demand — the metric’s components and drivers — returning each child as a { node, edge, handle } you can render and recurse into.

const revenue = world.metric("orders.net_revenue");

for (const child of await revenue.expand()) {
  console.log(child.node.label, child.edge.kind); // "Gross Revenue" "component"
  // child.handle.expand()  → recurse into the child's own drivers
}

// The declared drivers, ranked by influence (sensitivity).
const { drivers } = await revenue.drivers();
for (const d of drivers) console.log(d.measure, d.direction, d.strength);

Explain a move

explain decomposes a period-over-period change, recursively splitting the metric by its components and dimensions until the move concentrates — so you can show where a number came from, not just that it changed.

const profit = world.metric("financials.operating_profit");

const rca = await profit.explain({
  time_dimension: "financials.month",
  current_period: ["2026-06-01", "2026-06-30"],
  previous_period: ["2026-05-01", "2026-05-31"],
});

// rca.target_delta        — the top-line change
// rca.coverage            — fraction of the move explained
// rca.nodes               — the breakdown tree (each: split, delta, root_fraction)
// rca.driver_attribution  — how much each driver contributed
// rca.warnings            — Simpson's paradox, opposing offsets, non-additive splits

Size the opportunity

size finds underperforming segments and quantifies the upside of closing the gap to their peers — “match the best” across a dimension.

const revenue = world.metric("orders.net_revenue");

const opp = await revenue.size({
  time_dimension: "orders.order_date",
  period: ["2026-06-01", "2026-06-30"],
});

for (const dim of opp.dimensions) {
  console.log(dim.dimension, "+", dim.total_upside); // e.g. "region + 840000"
  for (const seg of dim.segments) {
    console.log(seg.segment, "gap", seg.gap, "upside", seg.upside);
  }
}

Drill into a segment

drill narrows a handle to a dimension = value segment and returns a new, scoped handle. Structural verbs (node, expand, drivers) are scope-invariant and keep working on it.

const west = world.metric("orders.net_revenue").drill({ region: "west" });
await west.expand();       // ✅ same structure, scoped handle
await west.explain({ ... }); // ⛔ throws — see below

explain and size on a drilled handle throw. The metric-tree backend cannot yet scope those analyses to a segment, so rather than silently return population numbers for a scoped question, a drilled handle throws a WorldModelScopeUnsupportedError from explain/size. Catch it and fall back to the un-drilled node, or gate the buttons on handle.scope:

import { WorldModelScopeUnsupportedError } from "@oxy-hq/sdk";

try {
  await west.size({ time_dimension: "orders.order_date", period });
} catch (e) {
  if (e instanceof WorldModelScopeUnsupportedError) {
    // scoped sizing isn't available yet — size the population node instead
  }
}

Simulate an action

Not built. Actions are the frontier of the World Model and have no SDK surface yet — the sketch below is the proposed shape, not a working API. Nothing in this section is callable today.

An action is a lever a human can pull — hire, raise prices, open a store. Actions would live in a catalog and declare only the leaf measure they directly move; everything downstream is already described by the metric tree’s drivers, so the SDK can propagate the effect for you — carrying the nonlinearity in the drivers.

// Proposed — not implemented.
const sales = world.metric("stores.net_sales");

const result = await sales.actions.hire.simulate({
  at: { store_id: "san_mateo" },
  magnitude: 1,          // hire 1 server
  horizon: "12w",
});

// result.impacts: PredictImpact[]
//   employees_per_shift  +0.071
//   service_score        +0.005   (linear-log driver)
//   net_sales            +$920/mo (piecewise driver — saturates past CSAT 4.8)

Because the nonlinearity lives in the driver, not the action, the same hire would produce a different lift depending on where each store sits on its curve — which is what makes size + simulate compose into a ranked recommendation:

Hire 2 servers at San Mateo → +0.14 CSAT (4.62 → 4.76) → +$28k/mo. Diminishing returns past a 3rd hire.

The knots of a piecewise driver are inspectable metadata, so the interface can say why the returns diminish rather than emit an opaque number.

The entity-graph hook

useWorldModel() now names the node interface above. The hook that returns the raw semantic-model entity graph — entities, their measures/dimensions, and how measures promote up the hierarchy — is now useWorldModelGraph().

import { useWorldModelGraph } from "@oxy-hq/sdk";

const { data, loading, error } = useWorldModelGraph();
// data.entities, data.edges  (the .world-model.yml display graph)

What it’s built on

The node interface is a thin composition layer over the metric-tree analyses that already ship — it adds no new backend. If you want the underlying calls directly:

React hooks — useMetricTree, useSensitivity, usePredict, useExplain, useOpportunity, useTimeDimensions, plus useBaseline and useProjection for scenario forecasting (same /semantic/metric-tree* endpoints, request/response shapes matching the server verbatim).
Node client — MetricTreeClient (getTree, getSensitivity, predict, explain, findOpportunities, getBaseline, getProjection) for API-key / server-side use — see Hooks & components.

These are the same analyses that power the IDE’s opportunity sizing and metric tree.

Try it

A runnable example lives in the SDK repo at sdk/typescript/examples/world-model-demo.tsx — an interactive explorer that starts at one top-line metric and walks the whole business from it (expand into drivers, explain a drop, size a gap), every object a live handle rather than a static number. Copy it into a bundle scaffolded with pnpm dlx create-oxy-app.

Next steps

The Metric Tree

Component vs. driver edges, forms, and promotion

Opportunity sizing

How the graph sizes a gap and decomposes it into drivers

Hooks & components

The stable SDK surface MetricTreeClient sits in

World Model

The semantic model, metric tree, and entity graph behind it

Get started

Data Infrastructure

World Model

Agentic Intelligence

SDK

Automations

Data Apps

Integrations

Edge fleet

Manage

Workspaces

Authentication

Observability

Enterprise

Reference

REST API

Resources

Troubleshooting

World Model Interface

The node paradigm

Get the interface

Expand into components and drivers

Explain a move

Size the opportunity

Drill into a segment

Simulate an action

The entity-graph hook

What it’s built on

Try it

Next steps

The Metric Tree

Opportunity sizing

Hooks & components

World Model

​The node paradigm

​Get the interface

​Expand into components and drivers

​Explain a move

​Size the opportunity

​Drill into a segment

​Simulate an action

​The entity-graph hook

​What it’s built on

​Try it

​Next steps

The Metric Tree

Opportunity sizing

Hooks & components

World Model

The node paradigm

Get the interface

Expand into components and drivers

Explain a move

Size the opportunity

Drill into a segment

Simulate an action

The entity-graph hook

What it’s built on

Try it

Next steps