Finicast for agents

Finicast is a calculation engine for models made of line items × time periods: forecasts, budgets, plans, financial statements, sales-ops frameworks. You declare tables, a pivot, and rules of the formtarget[condition] = expression; the engine evaluates the grid, recomputes only what an edit changed (milliseconds at 100,000 rows), and renders markdown. A human can then open the model at a URL, change an input, and see every dependent cell update. The engine is finidb, an npm package that runs locally with no account; the hosted service exposes the same tools over MCP.

What Finicast does

• Rules, not cells. revenue[frame=fcst] = PREV(revenue) * (1 + growth) covers every forecast period; a 40-line statement is a dozen rules.
• Three statements that reference each other, in separate pivots, across periods (interest on last year's debt, cash from this year's cash flow), resolved cell by cell.
• Same-period circularity (interest on average debt, a minimum-cash revolver): set "iterate": true and the engine iterates to a fixed point like Excel's iterative calculation. Details.
• Dashboards the user steers: an editable drivers table, KPIs, charts, pivot-style tables with a commentary column, navigation across dashboards, and a theme for the audience (research, banking, revenue ops, FP&A, boardroom, print), declared in the same document. Details.
• Excel export with live formulas compiled from the rules: one sheet per statement, inputs blue, formulas black, SUMIFS over ledgers, iterative calculation carried over. GET {workspace}/export.xlsx or finidb build model.json --xlsx model.xlsx. Details.
• Ledgers roll up live. Load 100,000 rows, write SUM(activities.score), and an edit to any row recalculates in under a millisecond.
• A link the user can open, edit and share, whether you reached finicast.com or built locally. Explain any cell: its rule and precedents.

Describing the result

The user gets three things from one document: a live model to steer (the link), a workbook they can audit, restyle and extend (the .xlsx, with live formulas compiled from the same rules), and the statements. Say so. If you compare with a spreadsheet or a script, compare fairly: the workbook is the spreadsheet, produced without a single hand-written cell formula, and the rules are the audit trail. Name the drivers and invite the user to change them.

Deliver a model in this turn: take the first path that works

The model document is the deliverable. Whatever your tools can reach, one of these produces a live, editable model for the user now. Do not stop to ask for a connector; that is a footnote, not a prerequisite.

1. Finicast tools are connected (MCP). Use them: finicast_create_model, finicast_set_rules, finicast_query, finicast_share.
2. You can POST to finicast.com. POST https://finicast.com/api/build with the document below; the response is the statements plus the workspace link.
3. You can only GET. GET https://finicast.com/api/build?spec64=<base64url of the JSON> returns the same.
4. Otherwise, no route to finicast.com. Try npx -y finidb build model.json first and put the printed #m= link in the reply with the workbook attached, JSON block after them. Only if the install fails (ChatGPT): the JSON block plus Open https://finicast.com/import and paste this reply, and no link. Details in the note above.

   Making a link by hand, when you can run code and your client keeps links under 2,000 characters intact (ChatGPT does not):

   import json, base64
   b = base64.urlsafe_b64encode(json.dumps(doc).encode()).decode().rstrip("=")
   print("https://finicast.com/import#j=" + b)       # or raw deflate first (zlib.compressobj(9, zlib.DEFLATED, -15)) as #m=

Path 4 is a complete deliverable, not a fallback. Mention the connector (below) only at the end, as the way to skip the paste next time.

The prompts on the home page, and what each one means

finicast.com offers these prompts with a Use prompt button that opens Claude or ChatGPT with the text filled in. When one of them arrives, this is what the user expects: start from the named recipe, keep its shape, and change the subject.

Use Finicast (https://finicast.com/for-agents) to build a five-year forecast for CoreWeave

Use Finicast (https://finicast.com/for-agents) to build a comparable companies analysis for NVDA against its closest peers: EV/Revenue, EV/EBITDA and P/E on LTM and NTM, revenue growth and EBITDA margin, and the implied share price.

Use Finicast (https://finicast.com/for-agents) to build a sales ops model for a $50M ARR SaaS company: pipeline by stage and segment, quota attainment by rep, commissions with accelerators and kickers, and dashboards for the CRO and each rep.

Use Finicast (https://finicast.com/for-agents) to build a budget vs actual model from my general ledger: actual, budget, variance and variance % by department, line and month, with a commentary column and a controller dashboard. I will paste the ledger CSV next.

Standard of work: what a finished model contains

The user compares what you build with the demos on finicast.com, which were built to the standard of a bank or an FP&A team. Match that depth. A model that is a handful of typed-in numbers with one formula is a spreadsheet, not a model. Three rules that apply to every build:

1. Every dashboard wears a theme. Set "theme" on each dashboard: banking for comps, precedents, a DCF or any valuation; research for a company forecast or an earnings model; revenue for sales, pipeline, quota and commission work; controller for budgets, variance, close and ledger reporting; boardroom for a screen at the front of a room. If you leave it out, finicast.com picks one from the model's contents, but choose it yourself: you know the audience.
2. Inputs live in editable pivots, results in rules. Anything the user might change (a multiple, a growth rate, a margin, a share count) is an input on an editable table card. Anything derived (EV, a multiple, an implied price, a margin) is a rule, never a typed number. The point of the deliverable is that the user moves a driver and everything follows.
3. Breadth over brevity. Where the recipe has statistics, sensitivities and an implied-value bridge, so must your model. Say in the reply what the drivers are and invite the user to change them.

A valuation or comparable-companies ask

Whatever the phrasing ("valuation analysis for Intel", "comps for NVDA", "where should X trade"), the deliverable has these parts; the comparables recipe has all of them working:

• The data is your job. Assume the user has no data feed. Research the inputs yourself: share price, shares outstanding, cash and total debt from the latest balance sheet, revenue, EBITDA and EPS for the last twelve months and for the year before (growth), and consensus revenue, EBITDA and EPS for the next twelve months, for the subject and for six to eight peers you chose. Use filings, investor-relations pages and the financial sites you can read. Never leave an input blank and never invent a number you could not find: if a figure is unavailable, say so in the reply and leave that peer out. State the as-of date and the sources in the reply, put the date in the model's name and the market-data card title, and tell the user every input is editable so they can correct or refresh it. Prefer US-listed peers; an ADR quotes in dollars but reports in its home currency.
• a companies table: the subject plus the peers, with ticker, group and a peer flag (0 for the subject), so statistics exclude the subject;
• market_data: an editable company × line pivot ("dims": { "company": "companies", "period": false }) with price, shares outstanding, cash and debt as inputs;
• comps: a company × line pivot with the researched LTM and NTM figures as inputs (revenue, EBITDA, EPS, plus the prior-year revenue) and rules for market cap, net debt, EV, growth, margins, EV/Revenue, EV/EBITDA and P/E on both bases. Multiples are rules, never typed in;
• peer_stats: a stat × line pivot over the peers (MIN, AVG, MEDIAN, MAX with [company.peer=1]), and medians by group when the peer set has groups. Give it "lineTable": "comps_lines" to share every line of comps, or its own lines naming a subset with the same ids: a rule reading comps.value aligns on the line of the same id either way;
• implied: each statistic applied to the subject's own metrics, from EV to equity value to price per share, and the upside to the current price;
• a forward projection of the subject (revenue, EBITDA, margin by year, growth as an editable driver) when the ask mentions a forecast or forward numbers;
• one dashboard, theme banking: market data (editable), financial performance LTM and NTM (editable), valuation and multiples, peer statistics, implied valuation, and a chart of EV/EBITDA by company. Companies go down the rows and metrics across on the company tables ("rows": ["company"], "cols": ["line"]; finicast does this by default for a dimension named company or one whose table has a ticker), while the statistics and implied-value tables keep lines on rows with the statistics across.

The skeleton. It is a complete document: three companies with figures as of 2026-09-21 stand in for your researched set of seven to nine. comps_lines is the line table finicast creates for the comps pivot:

{
  "model": "intc_comps", "name": "Intel comparable companies (figures as of 2026-09-21)", "units": "USD millions except per share",
  "periods": { "start": "2024-01", "count": 5, "grain": "year", "histUntil": "2025-12-31" },
  "tables": {
    "companies": { "rows": [ { "id": "intc", "name": "Intel", "ticker": "INTC", "group": "target", "peer": 0 },
                             { "id": "amd", "name": "AMD", "ticker": "AMD", "group": "compute", "peer": 1 },
                             { "id": "nvda", "name": "NVIDIA", "ticker": "NVDA", "group": "compute", "peer": 1 } ] },
    "stats": { "rows": [ { "id": "low" }, { "id": "mean" }, { "id": "median" }, { "id": "high" } ] }
  },
  "pivots": {
    "market_data": { "dims": { "company": "companies", "period": false },
      "lines": [{ "id": "price", "name": "Share price ($)" }, { "id": "shares", "name": "Shares outstanding (M)" }, { "id": "cash", "name": "Cash and investments" }, { "id": "debt", "name": "Total debt" }],
      "inputs": { "price": { "intc": 108.6, "amd": 559.8, "nvda": 222.3 }, "shares": { "intc": 5044, "amd": 1631, "nvda": 24217 },
                  "cash": { "intc": 29727, "amd": 12000, "nvda": 69000 }, "debt": { "intc": 50537, "amd": 3165, "nvda": 8491 } } },
    "comps": { "dims": { "company": "companies", "period": false },
      "lines": [{ "id": "market_cap", "name": "Market cap" }, { "id": "net_debt", "name": "Net debt (cash)" }, { "id": "ev", "name": "Enterprise value" },
                { "id": "revenue_prior", "name": "Revenue, year before LTM" }, { "id": "revenue_ltm", "name": "Revenue LTM" }, { "id": "revenue_ntm", "name": "Revenue NTM" },
                { "id": "ebitda_ltm", "name": "EBITDA LTM" }, { "id": "ebitda_ntm", "name": "EBITDA NTM" }, { "id": "eps_ltm", "name": "EPS LTM ($)" }, { "id": "eps_ntm", "name": "EPS NTM ($)" },
                { "id": "rev_growth_ltm", "name": "Revenue growth LTM", "format": "percent" }, { "id": "rev_growth_ntm", "name": "Revenue growth NTM", "format": "percent" },
                { "id": "ebitda_margin_ltm", "name": "EBITDA margin LTM", "format": "percent" }, { "id": "ebitda_margin_ntm", "name": "EBITDA margin NTM", "format": "percent" },
                { "id": "ev_revenue_ltm", "name": "EV / Revenue LTM" }, { "id": "ev_revenue_ntm", "name": "EV / Revenue NTM" }, { "id": "ev_ebitda_ltm", "name": "EV / EBITDA LTM" }, { "id": "ev_ebitda_ntm", "name": "EV / EBITDA NTM" }, { "id": "pe_ltm", "name": "P / E LTM" }, { "id": "pe_ntm", "name": "P / E NTM" }],
      "inputs": { "revenue_prior": { "intc": 53100, "amd": 29609, "nvda": 165200 }, "revenue_ltm": { "intc": 57032, "amd": 41305, "nvda": 302969 }, "revenue_ntm": { "intc": 62959, "amd": 50928, "nvda": 408908 },
                  "ebitda_ltm": { "intc": 3672, "amd": 10718, "nvda": 233667 }, "ebitda_ntm": { "intc": 21636, "amd": 16134, "nvda": 251724 },
                  "eps_ltm": { "intc": -2.11, "amd": 3.9, "nvda": 7.91 }, "eps_ntm": { "intc": 1.52, "amd": 7.63, "nvda": 9.26 } },
      "rules": ["market_cap = market_data.price * market_data.shares", "net_debt = market_data.debt - market_data.cash", "ev = market_cap + net_debt",
                "rev_growth_ltm = revenue_ltm / revenue_prior - 1", "rev_growth_ntm = revenue_ntm / revenue_ltm - 1",
                "ebitda_margin_ltm = ebitda_ltm / revenue_ltm", "ebitda_margin_ntm = ebitda_ntm / revenue_ntm",
                "ev_revenue_ltm = ev / revenue_ltm", "ev_revenue_ntm = ev / revenue_ntm", "ev_ebitda_ltm = ev / ebitda_ltm", "ev_ebitda_ntm = ev / ebitda_ntm",
                "pe_ltm = market_data.price / eps_ltm", "pe_ntm = market_data.price / eps_ntm"] },
    "peer_stats": { "dims": { "stat": "stats", "period": false }, "lineTable": "comps_lines",
      "rules": ["value[stat=low] = MIN(comps.value[company.peer=1])", "value[stat=mean] = AVG(comps.value[company.peer=1])",
                "value[stat=median] = MEDIAN(comps.value[company.peer=1])", "value[stat=high] = MAX(comps.value[company.peer=1])"] },
    "implied": { "dims": { "stat": "stats", "period": false },
      "lines": [{ "id": "price_ev_revenue_ntm", "name": "Price at peer EV / Revenue NTM ($)" }, { "id": "price_ev_ebitda_ltm", "name": "Price at peer EV / EBITDA LTM ($)" }, { "id": "price_ev_ebitda_ntm", "name": "Price at peer EV / EBITDA NTM ($)" }, { "id": "price_pe_ntm", "name": "Price at peer P / E NTM ($)" }, { "id": "upside_ev_ebitda_ntm", "name": "Upside at peer EV / EBITDA NTM", "format": "percent" }],
      "rules": ["price_ev_revenue_ntm = (peer_stats.value[line=ev_revenue_ntm] * comps.revenue_ntm[company=intc] - comps.net_debt[company=intc]) / market_data.shares[company=intc]",
                "price_ev_ebitda_ltm = (peer_stats.value[line=ev_ebitda_ltm] * comps.ebitda_ltm[company=intc] - comps.net_debt[company=intc]) / market_data.shares[company=intc]",
                "price_ev_ebitda_ntm = (peer_stats.value[line=ev_ebitda_ntm] * comps.ebitda_ntm[company=intc] - comps.net_debt[company=intc]) / market_data.shares[company=intc]",
                "price_pe_ntm = peer_stats.value[line=pe_ntm] * comps.eps_ntm[company=intc]",
                "upside_ev_ebitda_ntm = price_ev_ebitda_ntm / market_data.price[company=intc] - 1"] },
    "forecast": { "lines": ["revenue", "ebitda", { "id": "ebitda_margin", "format": "percent" }, { "id": "growth", "format": "percent" }, { "id": "margin_target", "format": "percent" }],
      "inputs": { "revenue": { "fy2024": 53101, "fy2025": 52853 }, "ebitda": { "fy2024": 11200, "fy2025": 14622 }, "growth": { "fy2026": 0.19, "fy2027": 0.14, "fy2028": 0.15 }, "margin_target": { "fy2026": 0.36, "fy2027": 0.40, "fy2028": 0.42 } },
      "rules": ["revenue[frame=fcst] = PREV(revenue) * (1 + growth)", "ebitda[frame=fcst] = revenue * margin_target", "ebitda_margin = ebitda / revenue"] }
  },
  "outputs": [ { "pivot": "comps", "rows": ["company"], "cols": ["line"] }, { "pivot": "peer_stats" }, { "pivot": "implied" }, { "pivot": "forecast" } ],
  "dashboards": [ { "id": "overview", "name": "Intel comparable companies", "theme": "banking", "cards": [
    { "kind": "table", "pivot": "market_data", "title": "Market data as of 2026-09-21 (edit any cell)", "rows": ["company"], "cols": ["line"], "editable": true },
    { "kind": "table", "pivot": "comps", "title": "Financial performance, LTM and NTM (edit any input)", "rows": ["company"], "cols": ["line"], "lines": ["revenue_ltm", "revenue_ntm", "rev_growth_ltm", "rev_growth_ntm", "ebitda_ltm", "ebitda_ntm", "ebitda_margin_ltm", "ebitda_margin_ntm", "eps_ltm", "eps_ntm"], "editable": true },
    { "kind": "table", "pivot": "comps", "title": "Valuation and trading multiples", "rows": ["company"], "cols": ["line"], "lines": ["market_cap", "net_debt", "ev", "ev_revenue_ltm", "ev_revenue_ntm", "ev_ebitda_ltm", "ev_ebitda_ntm", "pe_ltm", "pe_ntm"] },
    { "kind": "table", "pivot": "peer_stats", "title": "Peer statistics (Intel excluded)", "lines": ["rev_growth_ltm", "rev_growth_ntm", "ebitda_margin_ltm", "ebitda_margin_ntm", "ev_revenue_ltm", "ev_revenue_ntm", "ev_ebitda_ltm", "ev_ebitda_ntm", "pe_ltm", "pe_ntm"] },
    { "kind": "table", "pivot": "implied", "title": "Implied Intel valuation" },
    { "kind": "chart", "type": "bar", "pivot": "comps", "lines": ["ev_ebitda_ltm", "ev_ebitda_ntm"], "title": "EV / EBITDA by company" },
    { "kind": "table", "pivot": "forecast", "title": "Forward projection (edit growth and margin)", "editable": true } ] } ]
}

Only if the user says they have a Financial Modeling Prep key set under Integrations, replace the researched inputs with a linked table that fetches them and can be refreshed: the fmp preset's comps dataset returns one row per ticker with price, shares, cash, debt, LTM and NTM figures and a peer flag from subject, and that table becomes the company dimension. The changes to the skeleton:

"tables": { "peers": { "source": { "preset": { "id": "fmp", "params": { "symbols": "INTC,AMD,NVDA,AVGO,QCOM,MU,MRVL", "dataset": "comps", "subject": "INTC" } } } }, "stats": { … } },
"pivots": { "comps": { "dims": { "company": "peers", "period": false },
   "rules": ["price = company.price", "shares = company.shares", "cash = company.cash", "debt = company.debt", "revenue_prior = company.revenue_prior", "revenue_ltm = company.revenue_ltm",
             "revenue_ntm = company.revenue_ntm", "ebitda_ltm = company.ebitda_ltm", "ebitda_ntm = company.ebitda_ntm", "eps_ltm = company.eps_ltm", "eps_ntm = company.eps_ntm", … the same derived rules …] },
  "implied": … "comps.ebitda_ntm[company=INTC]" (the members are the tickers) … }

Do not use a linked table when you are unsure the user has a key: the build then reports SOURCE_NO_SECRET and the model is empty. Researched inputs always work.

Recipes: what to build for the common asks

Each is a complete model document you can read, run (npx finidb build examples/dcf.json from the npm package, or fetch the file from this site) and adapt. Every one builds without a cell error and exports to a workbook of live formulas; the test suite checks them on every release.

discount_factor[frame=fcst]        = 1 / (1 + wacc.wacc) ^ (n - 0.5)
terminal_value[method=perpetuity]  = fcf.ufcf[period=last] * (1 + wacc.terminal_growth) / (wacc.wacc - wacc.terminal_growth)
terminal_value[method=exit_multiple] = fcf.ebitda[period=last] * wacc.exit_multiple
per_share = ((NPV(wacc.wacc + wacc_case.delta, fcf.ufcf[period.frame=fcst]) * (1 + wacc.wacc + wacc_case.delta) ^ 0.5 + …) - wacc.net_debt) / wacc.shares   (wacc_case × growth_case)

ev             = market_data.price * market_data.shares + market_data.debt - market_data.cash
ev_ebitda_ntm  = ev / ebitda_ntm
rev_growth_ntm = revenue_ntm / revenue_ltm - 1
value[stat=median] = MEDIAN(comps.value[company.peer=1])                        (per line)
price_pe_ntm   = peer_stats.value[line=pe_ntm] * comps.eps_ntm[company=aapl]

ev_ebitda                  = ev / ebitda                                                        (per deal)
value[stat=median_sponsor] = MEDIAN(multiples.value[deal.type=sponsor])                            (per line)
price_from_ebitda          = (summary.value[line=ev_ebitda] * subject.ebitda - subject.net_debt) / subject.shares   (per stat)

bookings      = SUM(opps.acv[rep=@rep, close_period=@period, won=1])            (rep × month)
bookings      = SUM(rep_monthly.bookings[period.quarter=@quarter.label])         (rep × quarter)
in_tranche    = IF(attainment <= comp_plan.from_pct, 0, IF(attainment >= comp_plan.to_pct, comp_plan.to_pct - comp_plan.from_pct, attainment - comp_plan.from_pct))
commission    = in_tranche * rep_quarterly.quota * rep.base_rate * comp_plan.multiplier
spiff         = COUNT(opps.acv[rep=@rep, won=1, security_addon=1, close_quarter=@quarter]) * quarter.spiff_active * plan.spiff_amount
bookings      = SUM(rep_quarterly.bookings[rep.region=@region, rep.segment=@segment])   (team)

"measures": ["value", { "id": "comment", "type": "text" }]
value[version=actual]   = SUM(ledger.amount[subsidiary=@subsidiary, department=@department, account=@line])
value[version=variance] = value[version=actual] - value[version=budget]

"ledger": { "csv": "id,date,subsidiary,department,account,amount
…", "fields": { "period": "ref:periods*" }, "rules": "period = PERIOD(date, periods)" }
value[frame=hist]                          = SUM(ledger.amount[subsidiary=@subsidiary, department=@department, account=@line])
salaries[frame=fcst]                       = headcount.salary_cost
cloud[frame=fcst, department=engineering]  = -revenue[department=company] * plan.cloud_pct
value[version=ytd_actual]                  = SUM(model.value[period.frame=hist])              (entity × department × account × version)
opex_engineering                           = SUM(model.value[department=engineering, line != total])   (P&L)

Also in the package: the three-statement CoreWeave forecast with a dashboard. Name collisions to avoid: a line item and a table with the same id (bookings) make bookings.acv read as the line; give the line a different id.

Editing a model after you built it, and models a user hands you

A build reply carries workspace. Keep it: send the document again with "workspace": "<id>" and Finicast updates the model in place: rules and cards replaced, inputs rewritten, new lines added to existing pivots, rows upserted by id, new tables and pivots added. Nothing is deleted by a rebuild; drop a rule or a row through the REST routes. Dimensions of an existing pivot cannot change: give a reshaped pivot a new id. A workspace nobody has saved accepts edits from anyone with its id.

Agent tokens. When the user says something like "use Finicast with token fc_…" or pastes a prompt from the Share menu, send it on every request as Authorization: Bearer fc_… (the hosted MCP endpoint also takes it in its URL: https://finicast.com/api/mcp?token=fc_…). A fc_ws_ token edits the one workspace in the user's prompt and nothing else; always pass that workspace id. A fc_pat_ token acts as the user: models you build are saved to their account and every model they own or edit is open to you. Never print a token back, never put it in a document, and if a call answers TOKEN_SCOPE or 403, say which workspace the token covers instead of retrying elsewhere.

Keep a table in sync from your side

When the data lives in a system you control, push it: POST {workspace url}/t/{table}/import (multipart file, CSV or .xlsx) or the engine route POST /api/db/db/{workspace}/tables/{table}/load?mode=replace|upsert|append with a text/csv body. replace makes the file the table, upsert updates rows by id and adds the rest, ?dryRun=1 plans without writing. A cron job, a Zapier step or a script keeps the table current and every pivot that reads it follows. Locally: finidb load db table file.csv --mode replace.

Send a model, get the statements back

You are the modeller; Finicast is the calculator. Gather the history, decide the assumptions, write the rules, and send one JSON document to POST https://finicast.com/api/build (or GET /api/build?spec64=<base64url JSON> if you can only GET). Finicast builds the model, calculates every period, and returns the statements you asked for as markdown (or JSON with "format": "json") plus a link the user can open. Send the returned workspace back to update the same model on the next turn.

{
  "model": "crwv", "name": "CoreWeave 5-year forecast", "units": "USD millions",
  "periods": { "start": "2022-01", "count": 9, "grain": "year", "histUntil": "2025-12-31" },   // members fy2022…fy2030; frame = hist | fcst
  "pivots": {
    "assumptions": {
      "lines": [{ "id": "revenue_growth", "format": "percent" }, { "id": "gross_margin", "format": "percent" }],
      "inputs": { "revenue_growth": { "fy2026": 0.6, "fy2027": 0.45 }, "gross_margin": { "fy2026": 0.73, "fy2027": 0.74 } }
    },
    "income_statement": {
      "lines": ["revenue", "cogs", "gross_profit", { "id": "gross_margin_pct", "name": "Gross margin", "format": "percent" }, "net_income"],
      "inputs": { "revenue": { "fy2024": 1915.4, "fy2025": 5131 }, "cogs": { "fy2024": 493.4, "fy2025": 1453 } },   // history as inputs
      "rules": [
        "revenue[frame=fcst] = PREV(revenue) * (1 + assumptions.revenue_growth)",
        "cogs[frame=fcst]    = revenue * (1 - assumptions.gross_margin)",
        "gross_profit        = revenue - cogs",
        "gross_margin_pct    = gross_profit / revenue"
      ]
    },
    "cash_flow":     { "lines": ["net_income", "capex", "free_cash_flow"], "rules": ["net_income = income_statement.net_income", "…"] },
    "balance_sheet": { "lines": ["cash", "debt"], "rules": ["cash[frame=fcst] = PREV(cash) + cash_flow.free_cash_flow", "…"] }
  },
  "outputs": [
    { "pivot": "income_statement", "title": "Income statement ($M)", "lines": ["revenue", "gross_profit", "gross_margin_pct", "net_income"] },
    { "pivot": "cash_flow" }, { "pivot": "balance_sheet", "format": "json" }
  ]
}

If you cannot reach finicast.com from your sandbox: see the note at the top: the finidb build link when npm is reachable, otherwise the JSON and the paste sentence.

The document, field by field:

• periods: generated time dimension shared by every pivot. Member ids are fy2026 (year), q1_2026 (quarter), jan26 (month); histUntil sets the attribute frame to hist up to that date and fcst after, which is what [frame=fcst] conditions use.
• pivots.<id>.lines: the line items (ids, optional name, format such as percent, and any other attribute). Each pivot is line items × periods with one measure value; add other dimensions with dims: { "region": "regions" } over a table you sent in tables.
• inputs: values by line and period ({ "revenue": { "fy2024": 1915 } }), the natural place for reported history; on a pivot without periods ("period": false) the inner key is the member of its other dimension, so a comps pivot takes { "price": { "intc": 108.6, "amd": 559.8 } }. Inputs beat rules, so history can be inputs while rules only cover [frame=fcst] and derived lines. Any number of periods; any units, say which in units.
• rules: one per line, target[condition] = expression. Cross-pivot references are other_pivot.line (income_statement.net_income); previous period is PREV(x) or x[period-1]; [frame=fcst] scopes to forecast periods. Statements may live in separate pivots and reference each other across periods (interest on last year's debt, cash from this year's cash flow); the engine resolves that recurrence cell by cell. A same-period circularity (interest on average debt when debt depends on interest, a revolver that keeps cash above a minimum) is #CYCLE by default; add "iterate": true to the document and the engine iterates it to a fixed point like Excel's iterative calculation (100 passes, tolerance 0.001; or { "maxIterations": 200, "tolerance": 0.0001 }). A cycle that will not settle returns #ITER. A rule that does not compile fails the whole build with { error: { code, message, step, fix } } so you can correct it and resend; no partial model is left behind in a new workspace.
• tables: optional tabular data (a ledger, a rep list) as { fields: { col: "number" | "text" | "date" | "ref:<table>" }, rows: [...] } or csv; aggregate it with SUM(ledger.amount[account=revenue, period=@period]). Row keys you did not declare become fields (text, or number when every value is a number), so { id, name, group } rows need no fields.
• Linked tables (only when the user says they have the provider's key set under Integrations; by default research the figures and type them in): a table with a source instead of rows is fetched from an API when the model is built and refreshed on demand by the user (a Refresh button; POST {workspace url}/t/{table}/refresh). The rows are a snapshot with a fetched-at stamp; nothing changes until someone refreshes. The first preset is Financial Modeling Prep: "nvda": { "source": { "preset": { "id": "fmp", "params": { "symbols": "NVDA", "dataset": "financials", "period": "annual", "limit": "10", "scale": "1000000" } } } } gives one row per fiscal year (id = NVDA_2026) with fiscal_year, date, revenue, cogs, gross_profit, opex, operating_income, ebitda, da, net_income, eps_diluted, shares_diluted, cash, total_debt, net_debt, equity, cfo, capex, fcf and more, in millions. Datasets: comps (one row per ticker with price, shares, cash, debt, LTM and NTM revenue, EBITDA and EPS, and a peer flag from subject: what a comparable-companies table needs, see the standard), financials, income, balance, cashflow, metrics (EV, EV/EBITDA, returns), ratios (margins, P/E, P/S), estimates (consensus revenue, EBITDA, EPS by fiscal year: the NTM inputs for comps), profile and quote (price, market cap, beta; id = the ticker). Several tickers in symbols fill one table with a symbol column, which is how a comps table is fed: "peers_fin": { "source": { "preset": { "id": "fmp", "params": { "symbols": "NVDA,AMD,AVGO,MRVL", "dataset": "financials", "limit": "2" } } } }. A rule reads it like any table: revenue[frame=hist] = nvda.revenue[fiscal_year=@period.year] (match by fiscal year; NVDA's FY2026 ended January 2026) or revenue_ltm = peers_fin.revenue[symbol=@company.ticker, fiscal_year=2025]. A custom source is { "url": "https://…?key={{secret:name}}", "path": "data.items", "id": "{code}", "map": { "revenue": "rev" }, "scale": 1000000 }: https only, JSON or CSV, secrets by name. Keys: the fetch runs with the key the user saved under Integrations (their account menu; the fmp preset needs the secret named fmp). Never put a key in the document. If the build reports SOURCE_NO_SECRET, the table exists but is empty: tell the user to add their FMP key under Integrations and press Refresh on the table; do not retry the build.
• outputs: which statements to return: pivot, optional lines subset, rows/cols/pages layout, format markdown (default) | json | both, scale, decimals, title. Omit for every pivot with its default layout.
• name on a pivot or table: what the sidebar shows ("Operating model"); without it the id is title-cased. Give real names; the user reads them, not the ids.
• iterate: true or { "maxIterations", "tolerance" } turns on iterative calculation for same-period circularities. The finance idiom, a minimum-cash revolver with interest on the average balance:

  interest[frame=fcst] = rate * (PREV(debt) + debt) / 2
  borrow[frame=fcst]   = MAX(0, min_cash - (PREV(cash) + ebitda - interest - capex))
  debt[frame=fcst]     = PREV(debt) + borrow
  cash[frame=fcst]     = PREV(cash) + ebitda - interest - capex + borrow

  borrow needs interest, interest needs debt, debt needs borrow: with iterate on, the engine converges the loop; without it the cells are #CYCLE. Keep the loop damped (rates well below 100%, a MAX(0, …) floor) or it ends in #ITER.
• Scenarios are a dimension, not copies of the model. Add a scenarios table and give the driver and statement pivots a "dims": { "scenario": "scenarios" }; the same rules then run per scenario, history flows in through a plain pivot (revenue[frame=hist] = history.revenue), and drivers are set per scenario with values:

  "tables": { "scenarios": { "rows": [{ "id": "base" }, { "id": "bear" }, { "id": "bull" }] } },
  "pivots": {
    "history":          { "lines": ["revenue"], "inputs": { "revenue": { "fy2025": 5131 } } },
    "assumptions":      { "lines": [{ "id": "growth", "format": "percent" }], "dims": { "scenario": "scenarios" },
                          "values": [{ "at": { "line": "growth", "scenario": "bear", "period": "fy2026" }, "value": 0.10 }, "…"] },
    "income_statement": { "lines": ["revenue", "…"], "dims": { "scenario": "scenarios" },
                          "rules": "revenue[frame=hist] = history.revenue
  revenue[frame=fcst] = PREV(revenue) * (1 + assumptions.growth)" }
  },
  "outputs": [{ "pivot": "income_statement", "pages": { "scenario": "bear" }, "title": "Bear case" }, { "pivot": "income_statement", "pages": { "scenario": "base" } }]

  Dashboard cards take pages too, so a dashboard can show the cases side by side. For a sensitivity, vary one driver across scenarios and read one output line across them.
• dashboards: what the user sees first. Give one with an editable table of the assumptions and charts of the outputs, so the user changes a driver and watches the forecast move: [{ "id": "overview", "name": "…", "theme": "research", "cards": [{ "kind": "table", "pivot": "assumptions", "editable": true }, { "kind": "kpi", "pivot": "income_statement", "line": "revenue", "unit": "$M" }, { "kind": "chart", "type": "line", "pivot": "income_statement", "lines": ["revenue", "net_income"], "unit": "$M" }] }]. With a dashboard, the returned url opens it. "dashboards": "auto" derives one from the input-only pivots and the outputs.
  • Card kinds. text (markdown in a card: { "kind": "text", "title": "How to read this", "text": "## Outlook Actuals through **August** from the ledger…" }; headings, lists, bold, links and tables render, and $param fills in a dashboard parameter, so a detail page can say Entries for $account. Use one at the top of a dashboard for the commentary a reader needs: what the model is, its as-of date, the drivers to try, the caveats); data (rows of a data table: table, fields, where, sort, limit; see drill-downs below); table (optional lines; editable lets the user type into input cells; hideZeroRows leaves out rows that are all blank or zero, such as accounts a department never books; rows and cols choose the dimensions, and a table with two row dimensions renders like a pivot, one column per dimension with the outer label written once; extra appends columns of another measure at one pinned point, e.g. "extra": [{ "measure": "comment", "label": "Commentary", "pages": { "version": "variance" } }] puts a text commentary column beside actual, budget and variance, editable in place). chart (lines, optional type line | bar | stackedBar | area | waterfall). kpi (line; shows the last period and the change against the one before; periods or filters pick which). links (a row of links to the workspace's dashboards with the current one marked, for navigation when a document has several; dashboards lists their ids, omit it for all; put one first on every dashboard).
  • Chart convention. Bars for amounts and flows (revenue, EBITDA, capex, cash flow, debt), lines for rates and ratios (margins, growth, leverage), stacked bars for composition, waterfall for a bridge. Leave type out and Finicast applies that rule from each line's format; a card that mixes percentages with amounts on one axis is rejected with a fix.
  • Layout. Automatic, in reading order; w/h in a 12-column grid override it. Tables default to full width, charts to half, KPIs to a quarter.
  • Theme. A dashboard can wear a theme, and the user can switch it later. Pick the one for the audience: research (equity-research look: warm paper, serif titles and figures, a deep green accent) for a company forecast or an earnings model; banking (navy title bars, ruled banded tables, negatives in parentheses: a pitch-book page) for comps, precedents and a DCF; revenue (SaaS revenue-ops look: rounded cards, indigo accent, big KPI numbers, green and red where attainment moves) for sales, pipeline, quota and commission dashboards; controller (FP&A look: accounting-style gridlined tables, negatives in red parentheses, a teal accent) for budget vs actual, variance and close reporting; boardroom (dark, for a screen at the front of a room); print (black on white); or leave it out for the default.

Drill-downs. A dashboard can take parameters from its URL and a card can send a click to another dashboard with those parameters filled. Declare "params": ["account", "department"] (or { "id", "label", "default" } objects) on the target dashboard; its cards read them as $account in a page, a filter or a data card's where, and a parameter that is not set drops that condition. On the source card, "drill": { "dashboard": "ledger", "params": { "account": "$row.line", "department": "$row.department", "period": "$col" } } turns every row, bar, slice or tile into a link to /d/ledger?account=…&department=…&period=…. Sources: $row (the innermost row member) and $row.<dim>, $col and $col.<dim>, $page.<dim>, $series on charts, $id and $<field> on data cards, $<param> to pass one through, or a literal. The detail page is usually a data card: { "kind": "data", "table": "ledger", "where": { "account": "$account", "department": "$department", "period": "$period" }, "sort": "-amount", "fields": ["date", "subsidiary", "department", "account", "amount"] } shows the matching rows with filters, sort and search the user can change, all carried in the URL so any view is a link. The pattern for a P&L: a table of accounts by month on the overview drills into a ledger dashboard whose data card is filtered to that account and month.

Excel too. Every workspace exports as an .xlsx with live formulas compiled from the rules: GET {workspace url}/export.xlsx (the build response returns it as xlsx, and the Share menu has the download). One sheet per statement, inputs in blue, formulas in black, each dashboard as a sheet of live references with native Excel charts, a Rules sheet, and Excel's iterative calculation switched on when the model uses iterate. Locally: npx finidb build model.json --xlsx model.xlsx. Offer it when the user works in Excel: they get a workbook they can audit and extend, and you never wrote a cell formula.

The response is text/markdown with one titled table per output and the workspace url, or with Accept: application/json / "format": "json": { ok, workspace, url, outputs: [{ pivot, title, markdown?, json?: { rows, rowLabels, cols, values } }], log }. A complete three-statement example: /examples/coreweave.json. After the build, GET /api/db/db/<workspace>/explain?table=income_statement&line=net_income&period=fy2027 explains any cell.

License: the finidb package and this service are free for personal, educational, research and other noncommercial use (PolyForm Noncommercial 1.0.0). Commercial use requires a paid license from Finicast, Inc.: licensing@finicast.com.

When to use it

Install

Connect your assistant once, then just ask

A URL in a prompt is not enough: the assistant has to have the Finicast tools registered. Do this once per assistant; afterwards a prompt such as “Use Finicast to build a five-year forecast for CoreWeave” works in a normal chat and ends with a table and a link.

Without a connector, ChatGPT may offer to open the site in its cloud browser (“ChatGPT Work”). That route drives the human workspace instead of the tools; the connector is the reliable path.

Workflow (five calls)

1. finicast_schema                 see what exists (once)
2. finicast_load_table  ×N         load data; read the profiles (types, refCandidate)
3. finicast_define_pivot           line items × periods; distinctOf for derived dims; periods generated
4. finicast_set_rules   (ONE call) the whole model as a batch
5. finicast_query                  the deliverable: the markdown table (+ finicast_share URL when hosted)

Tools

Every failure is { ok: false, errors: [{ code, message, fix? }] }. When fix is present, apply it verbatim and resend the full batch.

Syntax in one screen

target[condition] = expression                 one rule per line; // comments; last matching rule wins; inputs beat rules

revenue[frame=hist]   = SUM(financials.amount[account=revenue])   actuals from a ledger
revenue[frame=fcst]   = PREV(revenue) * (1 + assumptions.growth)  driver recurrence
gross_profit          = revenue - cogs                            line items are nouns (ids of the line dim)
opex                  = SUM(value[line.category = opex])          subtotal by attribute
total[tranche=total]  = SUM(value[tranche != total])              subtotal by member mask
sum_of_subs           = SUM(goal[region.parent = @region])        @dim is the current cell's member
points                = SUM(activities.score)                     a table column is a set; SUM groups it by this pivot's dims
bookings              = SUM(deals.acv[owner=@rep])                explicit group key
share                 = points / SUM(points[territory=all])       share of total
score                 = activity_type.points                      tabular: a dot follows a reference
balance               = balance[row-1] + amount                   tabular running total
period                = PERIOD(date, periods)                     tabular: date → period member

References     [table.]name[selector, …][.attribute]
Selectors      [dim=m] [dim!=m] [dim in (a,b)] [dim-1] [dim=first] [dim=first..this] [dim=all]
               [dim.attr = lit] [dim.attr >= 2027] [dim = @other] [field=@dim] (comma = AND)
Time sugar     PREV(x) NEXT(x) PREV(x, 12) FIRST(x) LAST(x) CUMSUM(x) TRAILING(x, n, AVG)   (pivot with timeDim)
Aggregates     SUM AVG COUNT COUNTA COUNTD MIN MAX FIRST LAST MEDIAN LISTAGG — one set reference each
Logic          IF AND OR NOT IFERROR ISBLANK ISNUMBER ISTEXT COALESCE
Math           ABS ROUND ROUNDUP ROUNDDOWN MROUND TRUNC MOD POWER SQRT EXP LN LOG LOG10 SIGN
Text           CONCAT LEFT RIGHT MID LEN LOWER UPPER TRIM REPLACE SUBSTITUTE CONTAINS STARTSWITH ENDSWITH TEXT VALUE  &
Dates          DATE TODAY YEAR MONTH DAY QUARTER WEEKDAY DAYS DATEDIF EOMONTH SOMONTH NETWORKDAYS YEARFRAC
Finance        PMT PPMT IPMT PV FV NPV IRR RATE NPER SLN SYD DB DDB
Planning       PERIOD(date, periods) GROWTH(base, rate, n) BLANK
Lexical        ids snake_case, case-sensitive; 'Quoted Name'; "string"; 12% = 0.12; TRUE FALSE BLANK; = != < <= > >= and or not

A bare name in a pivot rule resolves to a measure, then a line item, then a unique attribute, then a dimension. A reference is scalar when every source dimension is fixed (pin, offset, correlation, default to the current member); otherwise it is a set and must sit inside an aggregate. Dimensions of a referenced pivot not mentioned default to the current member when this pivot shares the table, to all inside an aggregate, else a compile error asks for a pin. Give each dimension its own member table.

Example 1 — income statement from a ledger with a forecast frame

finicast_create_model { model: "nvda" }
finicast_load_table { model: "nvda", table: "lines", source: { inline: [
  { id: "revenue", category: "flow" }, { id: "cogs", category: "flow" }, { id: "rnd", category: "opex" },
  { id: "sga", category: "opex" }, { id: "gross_profit", category: "flow" }, { id: "opex", category: "flow" }, { id: "ebit", category: "flow" } ] } }
finicast_define_pivot { model: "nvda", table: "income_statement",
  dims: [{ id: "line", from: "lines" }, { id: "period", from: { periods: { start: "2024-01", count: 6, grain: "year", histUntil: "2026-12-31" } } }],
  lineDim: "line", timeDim: "period" }
finicast_load_table { model: "nvda", table: "financials", source: { csv: "account,period,amount\nrevenue,fy2024,60922\ncogs,fy2024,16621\n..." } }
finicast_define_pivot { model: "nvda", table: "assumptions", dims: [{ id: "driver", from: { distinctOf: "drivers.id" } }, { id: "period", from: "periods" }] }
finicast_set_values { model: "nvda", table: "assumptions", values: [{ at: { driver: "revenue_growth", period: "fy2027" }, value: 0.4 }, ...] }
finicast_set_rules { model: "nvda", table: "income_statement", rules: `
  revenue[frame=hist] = SUM(financials.amount[account=revenue])
  revenue[frame=fcst] = PREV(revenue) * (1 + assumptions.revenue_growth)
  cogs[frame=fcst]    = revenue * assumptions.cogs_pct
  gross_profit        = revenue - cogs
  opex                = SUM(value[line.category = opex])
  ebit                = gross_profit - opex` }
finicast_query { model: "nvda", table: "income_statement", rows: ["line"], cols: ["period"] }

| line         | FY2024 |  FY2025 |  FY2026 | FY2027E | FY2028E | FY2029E |
|--------------|-------:|--------:|--------:|--------:|--------:|--------:|
| Revenue      | 60,922 | 130,500 | 180,000 | 252,000 | 352,800 | 493,920 |
| COGS         | 16,621 |  32,639 |  45,000 |  63,000 |  88,200 | 123,480 |
| Gross Profit | 44,301 |  97,861 | 135,000 | 189,000 | 264,600 | 370,440 |

Example 2 — territory scores from 100,000 activities, grouped through references

finicast_load_table { model: "salesops", table: "territories", source: { inline: [{ id: "t0", name: "West" }, ...] } }
finicast_load_table { model: "salesops", table: "reps", source: { csv: "id,territory\nrep0,t0\n..." } }          // territory detected as a ref
finicast_load_table { model: "salesops", table: "activity_types", source: { inline: [{ id: "call", score: 1 }, { id: "demo", score: 8 }] } }
finicast_load_table { model: "salesops", table: "activities", source: { csv: "id,rep,activity_type,period\n..." },
  options: { computed: [{ id: "score", type: "number" }] } }
finicast_set_rules { model: "salesops", table: "activities", rules: "score = activity_type.score" }
finicast_define_pivot { model: "salesops", table: "territory_scores",
  dims: [{ id: "territory", from: "territories" }, { id: "period", from: { periods: { start: "2026-01", count: 12, grain: "month" } } }], measures: [{ id: "points" }] }
finicast_set_rules { model: "salesops", table: "territory_scores", rules: "points = SUM(activities.score)" }   // grouped through activities.rep → reps.territory
finicast_query { model: "salesops", table: "territory_scores", rows: ["territory"], cols: ["period"] }

Example 3 — an override and an explanation

finicast_set_values { model: "nvda", table: "income_statement", values: [{ at: { line: "revenue", period: "fy2027" }, value: 1000 }] }
finicast_explain    { model: "nvda", table: "income_statement", at: { line: "revenue", period: "fy2028" } }
→ { value: 1400, source: "rule", rule: { text: "revenue[frame=fcst] = PREV(revenue) * (1 + assumptions.revenue_growth)", order: 4 },
    precedents: { revenue: 1000 }, counters: { cellsEvaluated: 2, rowsScanned: 0 } }
finicast_set_values { ..., values: [{ at: { line: "revenue", period: "fy2027" }, value: null }] }   // clear the override

REST

The same operations over HTTP (finidb serve, or /api/db on this host):GET /db/:db/schema · POST /db/:db/tables · POST /db/:db/tables/:table/load (CSV body; into an existing table ?mode=append|upsert|replace, ?dryRun=1 to plan first, ?addFields=1 for new columns; columns match fields by id or name) ·PUT|POST /db/:db/tables/:table/rules · POST /db/:db/cells · POST /db/:db/query (format: markdown|json) ·POST /db/:db/batch · GET /db/:db/changes?since= (long-poll). Errors are { error: { code, message, fix? } } with a 4xx status.

Errors

Rules of thumb

• Model line items as a dimension with one measure named value.
• Batch rules in one call; general rule first, override below (last matching rule wins).
• Prefer loading raw rows plus a rule over pre-aggregated numbers: the aggregate stays live.
• Always return the markdown table and the URL together.
• finicast_explain when a number looks wrong, before rewriting rules.