Build from blueprint
layerz_build_from_blueprintBuild/extend a model from a strict Blueprint. Each item carries a single name (visible label + formula identifier). Names must be unique within the model (case-insensitive). Callup items omit name — they inherit it from source. Multi-word names use back-ticks in formulas (e.g. `Annual Revenue` * 12). Use this for bulk creation of whole sections with their hierarchy; for incremental edits on a single item or two, prefer layerz_patch (which also supports section+children in one batch via temp id/parent). Recursive time-series (roll-forwards, cumulative trackers, indexation) use the lag suffix <name>_M-N / <name>_Q-N / <name>_Y-N (and <name>_M-$var for dynamic lag). Self-referencing lag is allowed (A = A_M-1 + delta) — only zero-lag self-reference (A = A + …) is rejected. Cross-granularity: _Y-1 on a monthly item = 12 periods, _Q-1 on monthly = 3, _Y-1 on quarterly = 4. At period 0 a lagged ref returns 0 (or opening_balance for balance items). For canonical BOP/EOP patterns prefer a balance item with opening_balance and children for the period deltas. Alternatively pass template_id (mutually exclusive with blueprint, discover via layerz_list_templates) to apply a stored template as a module: its blueprint is loaded server-side and merged in. After applying, read the template guide (its description, via layerz_get_template) and update the model FINANCE.md (layerz_set_finance_md) to match the project. Not available for read-only API keys.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | 'merge' (default): add to the existing model, reusing items by display_name. 'replace': wipe non-default sections first. | |
| dry_run | No | Validate the blueprint and report errors without writing anything. | |
| summary | Yes | Required: short human-readable note (3–100 chars) summarising what this change does. Shown as the label in the model version history. Be specific (e.g. "Renamed Revenue to Net Revenue", "Imported 2024 OPEX from Excel"). | |
| model_id | No | Target model UUID. Required for user-scoped API keys; ignored (or validated against scope) for model-scoped keys. | |
| blueprint | No | Strict Blueprint object. Shape: { project?: string, timelines?: { monthly?: {start,end}, yearly?: {start,end}, quarterly?: {start,end} }, lists?: [{ display_name, items: [{label, mapped_to?: Record<targetListDisplayName, sourceLabels[]>}] }], sections: [{ name: "P&L", items: [{ role: "assumption" | "formula" | "callup" | "balance" | "chart" | "dashboard" | "kpi" | "mini_table", name, timeline_ref?, value?, values?, formula?, item_style?, opening_balance?, liste_ref?, timeline_values?: Record<elementLabel, (number|null)[]>, children?: [{name}], … }] }], dashboards?: [{ name, items: [{role: "chart" | "kpi" | "mini_table", …}] }] }. At least one section is required. Items reference each other by display_name (formula inputs, callup source, chart series). Stock-flow pattern: declare a `balance` with `opening_balance` and put `callup` items inside its `items` referencing the source flows by name; outflows must be formulas that return negative values; break self-referencing cycles with the lag suffix `_M-1` / `_Q-1` / `_Y-1` on the balance name. Roll-forwards & recursion use the lag suffix `<name>_M-N` / `_Q-N` / `_Y-N` (self-referencing lag is allowed, e.g. `Tariff = Tariff_Y-1 * (1 + Inflation)`); for BOP/EOP prefer a `balance` with `opening_balance` and `children` for the period flows. Full roll-forward cookbook (debt, DSRA, rolling min DSCR, balance-list) in docs/mdk-format.md. List mode (per-element series via the lists registry): declare named lists in `lists: [{display_name:"Functions", items:[{label:"Engineering"},{label:"Sales"},{label:"G&A"}]}]`, then bind a consumer item via `liste_ref:"Functions"` and provide `timeline_values: {Engineering:[1200000,1500000], Sales:[800000,950000], "G&A":[400000,420000]}` keyed by **element label** (resolved to UIDs at compile time). Works for `assumption`, `formula`, and `balance`. Two-dimension breakdowns compose with `mapped_to` on the list element: `lists:[{display_name:"Products", items:[{label:"Pro"},{label:"Enterprise"}]}, {display_name:"Channels", items:[{label:"Direct", mapped_to:{Products:["Pro","Enterprise"]}}, {label:"Partner"}, {label:"Self-serve"}]}]` says channel Direct rolls up products Pro and Enterprise, enabling Revenue × Products × Channels cross-aggregation. Balance-list rule: a `balance` with `liste_ref` requires every list-typed child to share the same `liste_ref`; scalar children broadcast. Set `dry_run: true` to validate without mutating; errors come back with a path you can fix. Full schema: src/core/blueprint-schema.ts. | |
| template_id | No | Apply a stored template as a module instead of an inline blueprint (mutually exclusive with `blueprint`). Discover ids via layerz_list_templates. |