KPI Formula Calculator

Overview

You send the formula your business has agreed on and the numbers to put in it; we return the value and, step by step, how it was reached — every operation, its operands and its result — so a figure on a dashboard can be explained rather than defended. The grammar is deliberately small: decimal numbers, your input names, plus, minus, times, divide, brackets, and nine arithmetic functions. Nothing here executes code, no name resolves to anything outside the inputs you send, and there is no exponentiation, comparison or conditional — a KPI is a number, not a decision. Division by zero is your call rather than ours: refuse it, treat it as zero, or return no value at all, because a silent zero has ruined more dashboards than any other default in this area.

KPI definitions live in configuration, in spreadsheets and in three services that disagree, and the usual way to make them configurable is to hand a caller's string to an expression engine. Those engines reach method calls, class loading and reflection by design, so that shortcut is remote code execution with extra steps. What you get here is the configurable formula without the engine: a closed grammar, names that resolve only to the inputs supplied, and a trace so the number can be checked rather than believed.

When to use it

Scope

Non-goals

• Does not execute code, and cannot: there is no scripting or expression engine behind it, only a parser for a closed arithmetic grammar
• Does not read a metric from a database, an API or anywhere else — every number comes from inputs
• Does not offer comparisons, conditionals or booleans: a KPI is a number, not a decision
• Does not offer exponentiation, because one short expression can otherwise cost unbounded work
• Does not remember a formula between calls, and does not name or store KPIs

Properties

Capabilities

Cost & billing

Flat rate per invocation

File handling

How we handle your data

Input schema

Output schema

API contract

curl -sS -X POST "$BASE/v1/execute" -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' -d '{"skillKey":"business.kpi_calculate","input":{"formula":"(revenue - cost) / revenue","inputs":{"revenue":250000,"cost":180000},"scale":4}}'

import { Squillify } from "@squillify/sdk";

const sq = new Squillify({ apiKey: process.env.SQUILLIFY_API_KEY });

const { output } = await sq.execute("business.kpi_calculate", {"formula":"round((revenue - cost) / revenue * 100, 2)","inputs":{"revenue":250000,"cost":180000},"scale":2});

Errors

Other limits

Limitations

• Does not execute code, and cannot: there is no scripting or expression engine behind it, only a parser for a closed arithmetic grammar
• Does not read a metric from a database, an API or anywhere else — every number comes from inputs
• Does not offer comparisons, conditionals or booleans: a KPI is a number, not a decision
• Does not offer exponentiation, because one short expression can otherwise cost unbounded work
• Does not remember a formula between calls, and does not name or store KPIs
• Anything that needs a condition, a comparison or a lookup — that is not this grammar
• Gathering the inputs: fetch them first and send them
• General expression evaluation, which is what this skill deliberately is not

How to call

POST /v1/execute (requires authentication)

{
  "skillKey": "business.kpi_calculate",
  "input": {
    "formula": "round((revenue - cost) / revenue * 100, 2)",
    "inputs": {
      "revenue": 250000,
      "cost": 180000
    },
    "scale": 2
  }
}

Examples

{
  "formula": "round((revenue - cost) / revenue * 100, 2)",
  "inputs": {
    "revenue": 250000,
    "cost": 180000
  },
  "scale": 2
}

{
  "value": 28,
  "formulaTrace": [
    {
      "step": 1,
      "expression": "revenue - cost",
      "operands": [
        250000,
        180000
      ],
      "result": 70000
    },
    {
      "step": 2,
      "expression": "(revenue - cost) / revenue",
      "operands": [
        70000,
        250000
      ],
      "result": 0.28
    },
    {
      "step": 3,
      "expression": "((revenue - cost) / revenue) * 100",
      "operands": [
        0.28,
        100
      ],
      "result": 28
    },
    {
      "step": 4,
      "expression": "round(((revenue - cost) / revenue) * 100, 2)",
      "operands": [
        28,
        2
      ],
      "result": 28
    }
  ],
  "identifiersUsed": [
    "cost",
    "revenue"
  ],
  "tokenCount": 14,
  "scale": 2,
  "roundingMode": "HALF_UP",
  "identifiersUnused": []
}

{
  "formula": "safeDiv(sum(weekly), count, 0)",
  "inputs": {
    "count": 0,
    "weekly": [
      10,
      20,
      30
    ]
  },
  "scale": 2
}

{
  "value": 0,
  "formulaTrace": [
    {
      "step": 1,
      "expression": "sum(weekly)",
      "operands": [
        10,
        20,
        30
      ],
      "result": 60
    },
    {
      "step": 2,
      "expression": "safeDiv(sum(weekly), count, 0)",
      "operands": [
        60,
        0,
        0
      ],
      "result": 0
    }
  ],
  "identifiersUsed": [
    "count",
    "weekly"
  ],
  "tokenCount": 11,
  "scale": 2,
  "roundingMode": "HALF_UP",
  "identifiersUnused": []
}

Recommended use cases

• Keep one KPI definition in configuration and evaluate it identically everywhere
• Show the arithmetic behind a dashboard figure to whoever queries it
• Let a business user change a KPI formula without a code change, safely
• Aggregate a list of period figures with sum or avg inside a larger formula

Avoid for

• Anything that needs a condition, a comparison or a lookup — that is not this grammar
• Gathering the inputs: fetch them first and send them
• General expression evaluation, which is what this skill deliberately is not

Related skills

Composable with

Safety & privacy

• Runs without calling any external service.
• Your payloads are never stored permanently.
• Telemetry captures metadata only — never your payload contents.
• We never train models on your payloads.
• No human reviews your payloads.

Tags