@capsuleer/calc

Calculator module for Capsuleer agents. The world's most over-engineered calculator — but that's the point. Lets agents evaluate math expressions, round results, and crunch descriptive statistics, with every operation emitting a structured trace event so nothing gets lost in the noise.

capsuleer install calc

No dependencies. No eval(). No regrets.

API

Expressions

// Basic arithmetic
const result = await calc.evaluate("(42 * 1.5) + 8")
// → 71

// Math functions and constants
const hyp = await calc.evaluate("sqrt(pow(3, 2) + pow(4, 2))")
// → 5

const circle = await calc.evaluate("PI * pow(7, 2)")
// → 153.93804002589985

// Chaining with prior results
const raw = await calc.evaluate("1 / 3")
const clean = await calc.round(raw, 4)
// → 0.3333

Supported functions: sqrt, cbrt, abs, ceil, floor, round, log, log2, log10, sin, cos, tan, asin, acos, atan, atan2, pow, min, max

Constants: PI, E

Rounding

await calc.round(3.14159, 2)   // → 3.14
await calc.round(1234.5)       // → 1235  (nearest integer)
await calc.round(0.1 + 0.2, 10) // → 0.3  (float noise begone)

Statistics

const scores = [88, 92, 75, 100, 61, 84, 90]
const s = await calc.stats(scores)
// → {
//     count: 7,
//     sum: 590,
//     mean: 84.28...,
//     median: 88,
//     min: 61,
//     max: 100,
//     range: 39
//   }

Observability

{ "ok": true, "op": "calc.evaluate", "data": { "expr": "sqrt(144) + 3 ** 2", "result": 21 } }
{ "ok": true, "op": "calc.round", "data": { "value": 3.14159, "decimals": 2, "result": 3.14 } }
{ "ok": true, "op": "calc.stats", "data": { "count": 7, "result": { "mean": 84.28, "median": 88, ... } } }

Safety

evaluate() does not use eval(). Expressions are validated against an allowlist of characters and identifiers, then executed via new Function() with only the math environment in scope. Property access (.) and assignment (=) are explicitly blocked. Anything that doesn't look like a math expression throws immediately.

Policy

const capsule = await Capsule({
  policy: {
    calc: {
      evaluate: true,
      round: true,
      stats: true,
    }
  }
})

See the policy docs for the full rule syntax.