@nhtio/adk/lib/helpers/bignum

Arbitrary-precision numeric helpers for the bundled tools.

Remarks

ECMAScript numbers are IEEE-754 float64: arithmetic on user-supplied values can overflow to Infinity, underflow to 0, or silently lose precision (0.1 + 0.2 === 0.30000000000000004). The numeric tool batteries (statistics, data_structure, unit_conversion, math) route their aggregations and result formatting through this module so that:

• large in-range sums stay exact instead of overflowing (sum([1e308, 1e308]) → 2e308),
• precision is preserved end-to-end (sum([0.1, 0.2]) → 0.3),
• output is rendered to a caller-chosen number of significant digits (default 8) without the lossy Number.prototype.toPrecision/toFixed round-trip that mangles even safe integers (e.g. 9007199254740991 rendered as 9007199255000).

Internally this is backed by a single mathjs instance configured for BigNumber (which bundles decimal.js) at 64 significant digits — comfortably more than float64's ~15-17 and enough for the tools' needs without unbounded growth.

The tools still RECEIVE float64 numbers (the model's tool-call arguments are JSON-parsed to float64 upstream, and the typed-array input schemas reject NaN/Infinity/> 2^53 before the handler runs). BigNumber's job is the math and formatting in between, not the input boundary.

Variables

Variable	Description
DEFAULT_PRECISION	Default display precision (significant digits) for tool output.

Functions

Function	Description
bigMean	Exact arithmetic mean as a BigNumber. Caller guarantees nums.length > 0.
bigScale	value * fromFactor / toFactor computed without intermediate float64 over/underflow.
bigSum	Exact sum of a numeric array as a BigNumber (no float64 overflow/precision loss).
bigToNumber	Convert a BigNumber back to a JS number (for cases that must hand off a float64).
formatBig	Render a BigNumber (or JS number) to a string at precision significant digits.
toBig	Coerce a JS number to a BigNumber. Non-finite inputs are a caller bug (schemas reject them).