# SDK intelligence definitions

Every figure the ledger-first documents produce, defined once, with a worked example. This is written for an accountant to check. Each example is pinned by a test in `tests/test_intelligence_definitions.py`, so the arithmetic here is the arithmetic the code does.

The worked example is a synthetic Australian services company over 1 July to 30 September 2026 (92 days), reporting in AUD. Its books are the fixture reports the tests use.

## Conventions

- **Money** is quantised to two decimal places, half up, at every step where a figure is stored. Percentages are quantised to two places; days to one.
- **Tax.** Profit and loss figures are read as the ledger reports them. In Xero, an accruals-basis profit and loss is tax-exclusive; balance sheet balances (cash, receivables, payables) are tax-inclusive. The SDK does not convert either. A receivable balance is therefore compared with revenue that excludes tax, and the working capital note says the ledger's revenue stands in for credit sales.
- **Windows** are half-open: `window_start` inclusive, `window_end` exclusive. A report titled "1 July 2026 to 30 September 2026" is the window `2026-07-01` to `2026-10-01`.
- **Unknown stays unknown.** A figure whose inputs the books do not state is `None`, never zero, with the reason in a note.

## The books snapshot

| Term | Definition | Example |
|---|---|---|
| Revenue | Sum of account rows in sections classified `revenue` | Sales 84,000.00 + Consulting 12,500.00 = 96,500.00 |
| Cost of sales | Sum of rows in sections classified `cost_of_sales` | Subcontractors 21,000.00 |
| Gross profit | Revenue less cost of sales | 96,500.00 − 21,000.00 = 75,500.00 |
| Operating expenses | Sum of rows in sections classified `expense` | 38,000 + 4,180 + 6,600 + 2,310 + 1,450 + 1,930 = 54,470.00 |
| Other income, other expenses | Rows in `other_income` / `other_expense` sections | Interest 120.00; none |
| Net profit | Gross profit + other income − operating expenses − other expenses | 75,500 + 120 − 54,470 − 0 = 21,150.00 |
| Gross margin % | Gross profit ÷ revenue × 100 | 78.24% |
| Net margin % | Net profit ÷ revenue × 100 | 21.92% |
| Variable cost | Cost of sales plus any expense account the plan names in `variable_accounts` | 21,000 + Merchant Fees 1,930 = 22,930.00 |
| Fixed cost | All recorded cost less variable cost | 21,000 + 54,470 + 0 − 22,930 = 52,540.00 |
| Contribution | Revenue less variable cost | 96,500 − 22,930 = 73,570.00 |
| Contribution margin % | Contribution ÷ revenue × 100 | 76.24% |
| Cash | Sum of asset rows in the `Bank` section, plus any account the plan maps to `cash` | 41,200 + 15,000 = 56,200.00 |
| Receivables, payables, tax owed, inventory | Sum of rows the plan maps to that role; `None` when no account is mapped | 27,500.00; 9,800.00; 7,350.00; `None` |
| Cash net of tax | Cash less tax owed | 56,200 − 7,350 = 48,850.00 |
| Cost per day | All recorded cost ÷ days in window | 75,470 ÷ 92 = 820.33 |
| Cash cover days | Cash net of tax ÷ cost per day; `None` when recorded costs are too thin | 48,850 ÷ 820.33 = 59.5 |

**Foot checks.** The report's own stated Gross Profit and Net Profit rows must equal the computed figures within the plan's tolerance (default 0.05), and on the balance sheet total assets less total liabilities must equal total equity. Otherwise the snapshot is refused.

**Findings.** `COSTS_IMPLAUSIBLY_LOW` when all recorded cost is under `minimum_cost_share_percent` (default 5) of revenue. `NO_LABOUR_COST_RECORDED` when no cost account whose name contains wage, salary, payroll, superannuation, contractor, subcontract, consult, labour, director fee or drawings carries a balance.

## Break-even from the books

| Term | Definition | Example |
|---|---|---|
| Contribution margin | Contribution ÷ revenue (from the books when no margin document is supplied) | 76.24% |
| Fixed cost | The books' fixed cost, only when no cost register overlaps the window | 52,540.00 |
| Operating result | Contribution − fixed cost | 73,570 − 52,540 = 21,030.00 |
| Break-even revenue | Fixed cost ÷ contribution margin | 52,540 ÷ 0.7624 = 68,913.96 |
| Margin of safety % | (Revenue − break-even revenue) ÷ revenue × 100 | (96,500 − 68,913.96) ÷ 96,500 = 28.59% |

When the books carry `NO_COSTS_RECORDED` or `COSTS_IMPLAUSIBLY_LOW`, the fixed cost is left unknown and no break-even is stated.

## Working capital from the books

| Term | Definition | Example |
|---|---|---|
| Days sales outstanding | Receivable balance ÷ (revenue ÷ days in window) | 27,500 ÷ (96,500 ÷ 92) = 26.2 days |
| Days payable outstanding | Payable balance ÷ (all recorded cost ÷ days) | 9,800 ÷ (75,470 ÷ 92) = 11.9 days |
| Days inventory outstanding | Stock balance ÷ (cost of sales ÷ days); `None` when stock is unmapped; 0.0 when mapped to an account carrying nothing | `None` in the example |
| Cash conversion cycle | DSO + DIO − DPO; `None` when any lever is unknown | `None`; with stock mapped to nil: 26.2 + 0.0 − 11.9 = 14.3 days |
| Cash to free (payables) | (Target days − DPO) × daily cost, when DPO is under target | (30 − 11.9) × 820.33 = 14,847.90 |

The books do not age receivables, so nothing from them is ever called overdue.

## Cash calendar from the books

| Term | Definition | Example |
|---|---|---|
| Opening cash | The books' cash balance as at the balance sheet date | 56,200.00 |
| Scheduled event | A balance the caller dated: receivables in, payables and tax out, in week ⌈days ÷ 7⌉ | receivables 30 days → week 5 |
| Weekly operating outflow | Cost per day × 7, only when the books record enough cost | 820.33 × 7 = 5,742.31 |
| Closing cash, 13 weeks | Opening + inflows − outflows − 13 × weekly outflow | 56,200 + 27,500 − 9,800 − 7,350 − 74,650.03 = −8,100.03 |

A calendar with no operating outflow is marked an optimistic ceiling, in the words of the cash forecast engine it runs on.

## Tie-out to the books

| Term | Definition |
|---|---|
| Difference | Document amount − books amount |
| Difference % | |Difference| ÷ max(|books|, |document|) × 100 |
| Tied | |Difference| ≤ `tolerance_amount` (default 50.00) **or** difference % ≤ `tolerance_percent` (default 2.00) |
| Not comparable | The document drew the figure from the books, or the books do not state the balance |

Product revenue is compared as net revenue plus revenue no SKU claimed, because the ledger's revenue includes both.

## What an accountant should challenge

1. Whether reading profit and loss figures tax-exclusive and balances tax-inclusive is right for this ledger's settings (`SalesTaxBasis`, `LineAmountTypes`).
2. Whether the default variable cost (cost of sales only) matches how this business's costs behave.
3. Whether cost per day over a 92-day window is a fair run-rate for a business with seasonal or lumpy costs.
4. Whether a receivable balance over tax-exclusive revenue overstates days sales outstanding for this business's tax rate.