@capsuleer/calc 1.0.1

package/README.md

@@ -0,0 +1,95 @@
+# @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.
+
+```bash
+capsuleer install calc
+```
+
+No dependencies. No `eval()`. No regrets.
+
+---
+
+## API
+
+### Expressions
+
+```typescript
+// 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
+
+```typescript
+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
+
+```typescript
+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
+
+```jsonl
+{ "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
+
+```typescript
+const capsule = await Capsule({
+  policy: {
+    calc: {
+      evaluate: true,
+      round: true,
+      stats: true,
+    }
+  }
+})
+```
+
+See the [policy docs](https://axon.arclabs.it/docs/capsuleer/policy) for the full rule syntax.

package/capsuleer.manifest.json

@@ -0,0 +1,106 @@
+{
+  "name": "calc",
+  "version": "1.0.1",
+  "description": "Calculator module — evaluate math expressions, round numbers, and compute descriptive statistics",
+  "exports": [
+    {
+      "name": "evaluate",
+      "declaration": "declare function evaluate(expr: string): Promise<number>",
+      "schema": {
+        "parameters": {
+          "type": "object",
+          "properties": {
+            "expr": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "expr"
+          ]
+        },
+        "returns": {
+          "type": "number"
+        }
+      }
+    },
+    {
+      "name": "round",
+      "declaration": "declare function round(value: number, decimals: number): Promise<number>",
+      "schema": {
+        "parameters": {
+          "type": "object",
+          "properties": {
+            "value": {
+              "type": "number"
+            },
+            "decimals": {
+              "type": "number"
+            }
+          },
+          "required": [
+            "value",
+            "decimals"
+          ]
+        },
+        "returns": {
+          "type": "number"
+        }
+      }
+    },
+    {
+      "name": "stats",
+      "declaration": "declare function stats(values: Array<number>): Promise<{ count: number; sum: number; mean: number; median: number; min: number; max: number; range: number }>",
+      "schema": {
+        "parameters": {
+          "type": "object",
+          "properties": {
+            "values": {
+              "type": "array",
+              "items": {
+                "type": "number"
+              }
+            }
+          },
+          "required": [
+            "values"
+          ]
+        },
+        "returns": {
+          "type": "object",
+          "properties": {
+            "count": {
+              "type": "number"
+            },
+            "sum": {
+              "type": "number"
+            },
+            "mean": {
+              "type": "number"
+            },
+            "median": {
+              "type": "number"
+            },
+            "min": {
+              "type": "number"
+            },
+            "max": {
+              "type": "number"
+            },
+            "range": {
+              "type": "number"
+            }
+          },
+          "required": [
+            "count",
+            "sum",
+            "mean",
+            "median",
+            "min",
+            "max",
+            "range"
+          ]
+        }
+      }
+    }
+  ]
+}

package/index.ts

@@ -0,0 +1,94 @@
+import { defineModule } from "@capsuleer/core"
+
+type StatsResult = { count: number; sum: number; mean: number; median: number; min: number; max: number; range: number }
+
+// Safe expression evaluator — supports +, -, *, /, **, %, parens,
+// and a small set of math functions. No eval(), no arbitrary code.
+const ALLOWED = /^[\d\s\+\-\*\/\%\(\)\.\,]+$|^[\d\s\+\-\*\/\%\(\)\.\,sqrt|cbrt|abs|ceil|floor|round|log|log2|log10|sin|cos|tan|asin|acos|atan|atan2|pow|min|max|PI|E]+$/
+
+const mathEnv: Record<string, unknown> = {
+    sqrt: Math.sqrt, cbrt: Math.cbrt,
+    abs: Math.abs, ceil: Math.ceil, floor: Math.floor, round: Math.round,
+    log: Math.log, log2: Math.log2, log10: Math.log10,
+    sin: Math.sin, cos: Math.cos, tan: Math.tan,
+    asin: Math.asin, acos: Math.acos, atan: Math.atan, atan2: Math.atan2,
+    pow: Math.pow, min: Math.min, max: Math.max,
+    PI: Math.PI, E: Math.E,
+}
+
+function safeEval(expr: string): number {
+    const sanitized = expr.trim()
+    // Only allow digits, operators, parens, dots, commas, spaces, and known identifiers
+    if (/[^0-9\s\+\-\*\/\%\(\)\.\,a-zA-Z_]/.test(sanitized)) {
+        throw new Error(`Expression contains disallowed characters: ${expr}`)
+    }
+    // Block anything that looks like property access or assignment
+    if (/\.\s*[a-zA-Z]/.test(sanitized) || /=/.test(sanitized)) {
+        throw new Error(`Expression not allowed: ${expr}`)
+    }
+    const fn = new Function(...Object.keys(mathEnv), `"use strict"; return (${sanitized})`)
+    const result = fn(...Object.values(mathEnv))
+    if (typeof result !== "number" || !isFinite(result)) {
+        throw new Error(`Expression did not produce a finite number: ${result}`)
+    }
+    return result
+}
+
+const calc = {
+    async evaluate(expr: string): Promise<number> {
+        try {
+            const result = safeEval(expr)
+            console.log(JSON.stringify({ ok: true, op: "calc.evaluate", data: { expr, result } }))
+            return result
+        } catch (err: any) {
+            console.log(JSON.stringify({ ok: false, op: "calc.evaluate", data: { expr }, error: err.message }))
+            throw err
+        }
+    },
+
+    async round(value: number, decimals = 0): Promise<number> {
+        try {
+            const factor = Math.pow(10, decimals)
+            const result = Math.round(value * factor) / factor
+            console.log(JSON.stringify({ ok: true, op: "calc.round", data: { value, decimals, result } }))
+            return result
+        } catch (err: any) {
+            console.log(JSON.stringify({ ok: false, op: "calc.round", data: { value, decimals }, error: err.message }))
+            throw err
+        }
+    },
+
+    async stats(values: number[]): Promise<StatsResult> {
+        try {
+            if (values.length === 0) throw new Error("Cannot compute stats on an empty array")
+            const sorted = [...values].sort((a, b) => a - b)
+            const sum = values.reduce((a, b) => a + b, 0)
+            const mean = sum / values.length
+            const mid = Math.floor(sorted.length / 2)
+            const median = sorted.length % 2 === 0
+                ? (sorted[mid - 1] + sorted[mid]) / 2
+                : sorted[mid]
+            const result: StatsResult = {
+                count: values.length,
+                sum,
+                mean,
+                median,
+                min: sorted[0],
+                max: sorted[sorted.length - 1],
+                range: sorted[sorted.length - 1] - sorted[0],
+            }
+            console.log(JSON.stringify({ ok: true, op: "calc.stats", data: { count: values.length, result } }))
+            return result
+        } catch (err: any) {
+            console.log(JSON.stringify({ ok: false, op: "calc.stats", data: { count: values.length }, error: err.message }))
+            throw err
+        }
+    },
+}
+
+export default defineModule({
+    name: "calc",
+    version: "1.0.0",
+    description: "Calculator module — evaluate math expressions, round numbers, and compute descriptive statistics",
+    api: calc,
+})

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@capsuleer/calc",
+  "version": "1.0.1",
+  "description": "Calculator module for capsuleer — evaluate math expressions, round numbers, and compute descriptive statistics",
+  "type": "module",
+  "main": "./index.ts",
+  "types": "./index.ts",
+  "keywords": [
+    "capsuleer",
+    "calculator",
+    "math",
+    "statistics"
+  ],
+  "author": "cody",
+  "license": "MIT",
+  "dependencies": {
+    "@capsuleer/core": "latest"
+  },
+  "peerDependencies": {
+    "bun": ">=1.0.0"
+  }
+}