World Model Interface

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

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, coefficient, form

// Or focus a single node and expand it lazily — ideal for click-to-open UIs
// where you don't want the whole tree up front.
const revenue = world.metric("orders.net_revenue");
// revenue.node       — the measure itself (label, expr, value)
// revenue.expand()   → child nodes (components + drivers), fetched on demand
// revenue.drivers    → driver edges, ranked by influence (sensitivity)

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.nodes              — the breakdown tree (each node: split, delta, root_fraction)
// rca.driver_attribution — how much each driver contributed
// rca.warnings           — Simpson's paradox, opposing offsets, non-additive splits

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 + $840k"
  for (const seg of dim.segments) {
    console.log(seg.segment, "gap", seg.gap, "upside", seg.upside);
  }
}

// Actions applicable to a node (from the catalog's `applicable_actions` /
// `influenced_by` pointers).
const sales = world.metric("stores.net_sales");

// Simulate one lever at a specific entity instance, and read the projected
// delta after it flows through the drivers.
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)

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

<MetricTreeView
  root="orders.net_revenue"
  onSelect={(node) => {
    // node.expand()  → drivers as child cards
    // node.drill({ region: "west" })  → the same metric, scoped
    // node.explain({ period })        → inline root cause
    // node.size({ period })           → peer comparison
    setFocus(node);
  }}
/>