Fr8Labs Analytics

Ask a natural-language question about THIS tenant's freight data (shipments, jobs, parties, charges, on-time, margin) and get back rows + the SQL that produced them + a "data as of" freshness stamp. The question is turned into tenant-scoped SQL by the same governed generator the in-app analytics assistant uses; your companyId is derived from your token (you cannot query another tenant). Defaults to the fast warehouse mirror (refreshed ~twice daily — see the freshness stamp); pass dataSource:"live" only when you need up-to-the-minute data (slower). Results are capped (see rowCount/truncated) — if truncated, narrow the question or ask for an aggregate. Multi-company tokens: COMBINED queries across your companies run on the WAREHOUSE only — for live/real-time data, query ONE company at a time (pass a single companyId) and combine across companies yourself. When a multi-company answer breaks down BY company, the result includes a `companies` map ([{id,code,name,currency}]) — label each row with the company code/name (never the numeric companyId), and show money in each company's own `currency`; never sum money across currencies. UNBILLED / UNINVOICED / "TO BILL" JOBS: if the user asks how many jobs are unbilled / uninvoiced / not yet billed / still to bill (the billing backlog), you MUST FIRST ASK them whether to include completed-but-uninvoiced jobs before sending the question — do NOT assume. (Cancelled and non-billable jobs are always excluded.) Pass their choice through in the question text, e.g. "...unbilled jobs, active only" vs "...unbilled jobs, including completed".

ask_data

Assemble EXISTING saved cards (from build_card) into a Metabase DASHBOARD in your tenant's own collection — the multi-card companion to build_card. Build the cards first with build_card, then pass the dashboard `name` and a `cards` array (items in display order). Each item is EITHER a chart/table ({ cardId, display? }) OR a markdown text/heading block ({ text }) for a title, section header, or an executive-insight note. LAYOUT: just list the items in a sensible order and OMIT row/col/sizeX/sizeY — auto-layout arranges them into a clean, sectioned grid (KPI tiles into a top strip 4-up, charts 2-up, tables and text blocks full-width), so you never compute pixel coordinates. (Give ALL FOUR of row/col/sizeX/sizeY on EVERY item only when you want a precise screenshot-match layout.) RECIPE for a polished comparison / P&L dashboard: (1) a title `text` block (e.g. "# Q1 P&L — 2025 vs 2026"); (2) one KPI per headline metric, each a saved build_card with display:"smartscalar" (e.g. Revenue, Gross Profit, Overhead, Net Profit) — they line up into the top strip; (3) a `text` section header (e.g. "## 📈 Monthly Trend"); (4) one display:"bar" card per metric built from a per-month-per-year query (months render side-by-side per year, each metric in its own colour); optionally (5) a closing `text` header + a short insight `text` note. Every cardId must be one you are authorized for and within this dashboard's tenant (anti-IDOR; you cannot place another tenant's card). Chart cards auto-format their axes + data labels + compact numbers. Returns the dashboardId + a viewable embed URL.

create_dashboard

Stop + delete a scheduled report (Metabase subscription) by reportId (from list_reports). For an admin / multi-company token, pass the same `companyId` you listed under. You can only cancel reports for a company you are authorized for.

cancel_report

Modify an existing Metabase card through the SAME governed pipeline as ask_data (generate/validate + tenant-scope check) — the safe alternative to raw Metabase admin. Pass an `instruction` (natural language, e.g. "group by month" or "only FCL shipments") OR `sql` (+ `signedSql` from a prior ask_data). The edit ALWAYS stays scoped to the CARD's OWN company — you cannot retarget a card to another tenant. You may edit any card within your authorized scope, including cards created outside this tool, as long as the card's collection maps to a company you're authorized for. Read it first with get_card and check its scopeGuard: if the card's CURRENT SQL fails the tenant-scope guard (legacy hand-written cards often do), an `instruction` edit will ALSO fix the scoping as part of the same update (compliance upgrade — the saved SQL is always re-validated, fail-closed, so only compliant SQL can land). Expect a larger diff in that case; if generation still can't produce compliant SQL you get the guard's verdict — retry, or describe the FULL desired query to ask_data and pass its sql + signedSql here. Note: `instruction` edits run a full generation (can take 60-90s); prefer the sql+signedSql path when you already have the query.

edit_card

Fetch a card's current data and EMAIL IT ONCE, right now (no schedule). Pass `question` (or `cardId`, or `sql`+`signedSql`) + `name` (the email subject). Recipients DEFAULT to your own email; explicit recipients must be same-domain (anti-spam) and at most 5. Use this for "email me this now"; use schedule_report for a recurring send.

send_report_now

Turn a question (or a saved card) into a RECURRING email report for your tenant — or, for an admin / multi-company token, a client you name via `companyId` (on their behalf; it lands in THEIR Metabase). Pass `question` (or `cardId`, or `sql`+`signedSql`) + `name` + `cadence` (daily/weekly/monthly). Recipients DEFAULT to your own email; you may pass `recipients` but only same-domain addresses are allowed (anti-spam) and at most 5. ALWAYS run with dryRun:true first and show the user what would be scheduled (cadence + recipients), then re-run with dryRun:false to actually arm it. Returns the reportId + when it next sends. Manage with list_reports / cancel_report.

schedule_report

Return the companyId(s) this analytics token is authorized to read. A single-tenant token returns its one company; a multi-company token returns its set (pass one as ask_data's companyId to narrow, or omit to query the combined set); a team token can query ANY company (you must pass an explicit companyId to ask_data). Each company comes with its code (e.g. "DGFMY") and name in `companies` — show THOSE to the user, never the bare numeric companyId.

list_companies

List the recurring email reports (Metabase subscriptions) for your tenant — or, for an admin / multi-company token, a client you name via `companyId`. Shows name, cadence, recipients. Use cancel_report to stop one.

list_reports

LAST-RESORT live read of a named ERPNext financial report — to tie out against the GL in real time when the warehouse snapshot will not do. Prefer ask_data (warehouse: certified, scoped, faster) for routine analysis. Reports: trial-balance, balance-sheet, accounts-receivable, accounts-payable, general-ledger. Read-only; runs on the low-privilege posting key (AR/AP may need elevated access not available here — it will tell you to use the warehouse instead). No tenant argument — runs against your own server-derived tenant.

pull_live_erp_report

Read the definition (name, SQL, display type, company) of an existing Metabase card you are authorized to see — your own tenant's cards, or (multi-company tokens) any of your companies' cards. Use this before edit_card. The response includes scopeGuard {safe, reason}: when safe=false the card's CURRENT SQL predates the tenant-scope guard — an instruction-based edit_card will then ALSO fix the scoping as part of the edit (compliance upgrade), so expect a larger SQL diff than the instruction alone implies. You cannot read a card outside your authorized scope.

get_card