Skip to main content
The World Model is Oxygen’s formula-first model of your business. It defines every metric that matters as an equation over the drivers beneath it, so agents and applications can reason about why an outcome moved and what to do about it — not just report the number.

​
A control system for outcomes, not objects

Most operational tooling models a business bottom-up: it catalogs the atomic objects — every machine, part, and store — as a digital twin, so operators can watch those objects and understand why they break. That’s essential for integrity, but it orients you toward the minutiae. Oxygen models the business top-down. Metrics are outcomes, so we start at the outcome level — the top-line objective you’re accountable for — and orient downward from there, toward the drivers you can actually move. A digital twin is a control system for objects; the World Model is a control system for outcomes. If the goal is to drive the business forward, starting from the objective is, almost by definition, the better place to begin. The World Model is built from three layers. Each one adds structure the layer below it can’t express on its own.

​
1. Semantic Model — the vocabulary

The Semantic Model defines your business’s measures and dimensions once, in version-controlled .view.yml files, and compiles them into deterministic, correct SQL. Joins are resolved automatically from entity definitions, and fan-out is detected and neutralized — so labor_cost_pct means the same thing everywhere, and no agent has to hand-write (or hallucinate) a query to compute it.
This is the programmatic, deterministic foundation: business logic in, correct SQL out. Learn about the Semantic Model →

​
2. Metric Tree — the relationships

A single measure is a fact. The Metric Tree captures how measures relate, so a top-line metric decomposes into the driver metrics that explain it. Measures compose two ways:
  • Component edges — implicit, from {{view.measure}} references. arr depends on net_mrr, which depends on total_mrr and churned_mrr.
  • Driver edges — explicit drivers: annotations that encode a business relationship (direction, strength) rather than pure arithmetic.
Because the tree knows how every metric is built, it can decompose a change top-to-bottom — walking from the outcome to the drivers responsible. This is what powers root cause analysis (below).

​
3. Entity Graph — the objects

The Entity Graph links measures to the real objects that produce them — stores, employees, customers, orders — via entities declarations (primary / foreign keys) and a parent: hierarchy.
Two things fall out of this:
  • Automatic joins. Any measure can be sliced by any related object’s dimensions, because the graph knows the path between them.
  • Promotion up the hierarchy. A measure defined at the sale grain automatically rolls up to the store, company, and market — so markets.net_sales is derived, never redefined.
Grounding metrics in real objects is also what makes them actionable: an object is something you can take an action against.

​
From understanding to action

The layers above turn the World Model into a lever against the only two questions that matter day to day: what’s going wrong, and what should we do next.

Root cause analysis

What’s going wrong and why. Decompose a metric’s change across its drivers and segments, walking the metric tree and pruning down the entity hierarchy. Detected anomalies land in the Insights Inbox with an AI-authored root cause. Available today.

Opportunity sizing

What to do next and why. Compare each segment to its benchmark, size the gap, and propagate the top opportunity through the metric tree. On the roadmap.
For example, opening up labor_cost_pct for a location might read:
Actions are the frontier. The next layer — .action.yml files — will model the levers themselves: hire, raise prices, open a store. An action declares what it simulates (row-level changes to entities) or impacts (a modeled measure delta), so you can estimate its effect on the metric tree before committing. This layer is in design and not yet available.

​
Next steps

Semantic Model

Define measures, dimensions, and entities

Entities & relationships

How the entity graph resolves joins and hierarchy

Measures

Build the measures the metric tree composes

Use in agents

Put the World Model to work in Agentic Intelligence