> ## Documentation Index
> Fetch the complete documentation index at: https://oxy.tech/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# World Model
> Oxygen's control system for business outcomes — a formula-first model built from a semantic model, a metric tree, and an entity graph
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](/docs/guide/build/semantic-model/simple-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.
```yaml theme={null}
# sales.view.yml
measures:
- name: net_sales
type: sum
expr: amount
- name: labor_cost_pct
type: number
expr: "{{sales.labor_cost}} / NULLIF({{sales.net_sales}}, 0)"
dimensions:
- name: location
type: string
expr: location
```
This is the **programmatic, deterministic** foundation: business logic in,
correct SQL out. [Learn about the Semantic Model →](/docs/guide/build/semantic-model/simple-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.
```yaml theme={null}
measures:
- name: arr
type: number
expr: "{{revenue.net_mrr}} * 12"
drivers:
- measure: revenue.churn_rate
direction: negative
strength: strong
description: "Higher churn directly reduces ARR"
```
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.
```yaml theme={null}
# stores.view.yml
entities:
- name: store_id
type: primary
key: store_id
parent: company_id
```
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.**
**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.**
**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:
```text theme={null}
Labor cost: 37.5% (13% lower than average)
Root cause
revenue +25% vs average
labor +50% vs average
employees ~ average
full-time hours ~ average
overtime hours +100% vs average
Estimated adjustment: $250k labor cost
Recommendation: investigate overtime cost at the San Mateo location
```
**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
Define measures, dimensions, and entities
How the entity graph resolves joins and hierarchy
Build the measures the metric tree composes
Put the World Model to work in Agentic Intelligence