# How Limitr works: the policy, the engine, and each call

> The pieces of a Limitr policy (credits, plans, entitlements, customers, grants, caps), how the engine decides each call, and the events it sends.

# How Limitr works

Limitr has two parts:

- **The policy**: one document that says what each plan includes, how usage is counted, what it costs you, and what
  you charge.
- **The engine**: a small WebAssembly runtime inside your app that loads the policy, keeps each customer's state, and
  answers one question before anything that costs money: *is this allowed, and what is it worth?*

## The policy

| Piece | What it is | Ex. |
|---|---|---|
| [Credit](./reference/credits) | A unit you count, with what you charge and what it costs you. | An AI token: $20 per million charged, $8 per million cost. |
| [Plan](./reference/plans) | A named set of entitlements and topups. | Free, Pro, Enterprise. |
| [Entitlement](./reference/entitlements) | Something a plan allows. No limit: a feature flag. With a limit: metered in a credit. | `export_pdf`, `chat`, `seats`. |
| Limit | How much of a credit an entitlement includes, its mode, and when it resets. | 2M tokens a month, soft. |
| [Topup](./reference/grants-and-topups) | A credit pack on a plan. | 1M tokens for $15. |
| [Exchange](./reference/exchange) | Converts any credit into any other, through runes (US dollars by default). Currencies are credits too. | 1 AI credit is 1 cent; 1 euro is 1.14 USD. |
| [Notification](./reference/notifications) | A rule that watches events. | "Tell me when a customer has 10% left." |

A policy is a [Stof](https://stof.dev) document, a superset of JSON, so it can also be written in JSON, YAML, or TOML.
Stof adds units (`1GB`, `30days`) and functions, for the parts of pricing that aren't just numbers: a
[cost that depends on the model](./how-to/ai-token-costs), a [rollout rule](./reference/feature-rules), or a rule
of your own ([Extend Limitr](./how-to/extend-limitr)).

## Customers

A [customer](./reference/customers) is anything you meter: a user, an org, a team, an agent. Each has your ID, a plan,
a type, and **refs** to other customers (a user refs its org, and can be on the org's plan). The engine keeps each
customer's state:

- **Meters**: usage of each entitlement this period, and what it cost.
- **Overrides**: per-customer limits, Ex. a bigger allowance for one deal.
- **Gives and takes**: per-customer changes to which entitlements it has.
- **Grants**: credit balances from topups.
- **Caps**: spend ceilings, Ex. $50 a month across everything.

## A call

Your app asks before doing the work:

<Tabs groupId="lang" queryString>
<TabItem value="typescript" label="TypeScript">

```ts
if (await limitr.allow(customerId, 'chat', tokens)) {
    // call the model
}
```

</TabItem>
<TabItem value="python" label="Python">

```python
if limitr.allow(customer_id, 'chat', tokens):
    ...  # call the model
```

</TabItem>
</Tabs>

The engine decides in this order, and nothing changes until every step passes:

1. **Does the customer have the entitlement?** Its plan (or a give), not taken away, and on by its
   [feature rule](./reference/feature-rules), if it has one. A feature flag stops here.
2. **New period?** If the limit resets and a period ended, the meter starts over.
3. **Spend caps.** Every cap that applies has room.
4. **Grants** cover usage past the limit first.
5. **Rate.** A governor, if there is one, has tokens left.
6. **The limit**, by its mode:

| Mode | Past the limit |
|---|---|
| `hard` | Denied. |
| `soft` | Allowed, and the part past the limit is billed as overage. |
| `observe` | Allowed, and only recorded. |

7. **Commit.** The meter, its cost, grants, and caps move, and events are sent.

`check` makes the same decision without changing anything. For calls whose size you only know afterwards, like an
LLM call, [`reserve` and `settle`](./how-to/reserve-llm-calls) hold room first and record the real usage after.

Try the three modes: each entitlement allows 2 exports.

export const modes = {
    title: 'modes.stof',
    temp: true,
    policyFormat: 'stof',
    policy: `
policy: {
    credits: {
        export: { label: 'Export', price: { amount: 0.50 } }
    }
    plans: {
        pro: {
            default: true
            entitlements: {
                exports_hard: { limit: { credit: 'export', mode: 'hard', value: 2 } }
                exports_soft: { limit: { credit: 'export', mode: 'soft', value: 2 } }
                exports_observe: { limit: { credit: 'export', mode: 'observe', value: 2 } }
            }
        }
    }
}`,
    stof: `
#[main]
fn main() {
    self.policy.create_customer('ada');
    for (const entitlement in ['exports_hard', 'exports_soft', 'exports_observe']) {
        pln(entitlement);
        for (const i in 3) pln('  export', i + 1, '->', self.policy.allow('ada', entitlement, 1));
    }
}

#[meter-limit]
fn denied(event: obj) { pln('  meter-limit: denied at', event.meter.value, 'of', event.meter.limit); }

#[meter-overage]
fn overage(event: obj) { pln('  meter-overage: bill', event.overage_price); }
`,
};

<LimitrExample {...modes} />

## Events

Every change is reported as an [event](./reference/events), to your app's handlers and to the policy's notifications:
`meter-changed` for usage, `meter-overage` for usage to bill (with `overage_price`), `meter-limit` for a denial,
`cap-limit` when a budget stops a call, `customer-set` when a customer changes, and more. Meter events carry what the
call is worth (`meter.price_diff`) and what it cost you (`meter.overhead_diff`), so margin is known per call.

Limitr doesn't take payments. It decides what's billable and tells you; your app (or
[Limitr Cloud](./tutorial/going-to-cloud.md)) records it and your payment provider charges it. See
[Bill from events](./how-to/bill-from-events).

## Where it runs

The engine runs in your process: Python, Node, Bun, Deno, or the browser, with no network in the way. Policy functions run in
a sandbox, with no network, files, or environment unless your app allows them, and time and memory limits on every call. The engine itself is sealed, so a policy can build on it but can't change it. See [Runtime and sandbox](./reference/runtime) and the [Security model](./reference/security).

Customer state lives in the engine's memory. Self-hosted, you [save it](./how-to/save-customer-state) in your
database. With Limitr Cloud, it's stored and synced across every server for you.
