@nhtio/adk 0.1.0-master-f0aa531d

package/batteries/tools/statistics.cjs

@@ -0,0 +1,253 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+require("../../chunk-KmRHZBOW.js");
+const require_tool_registry = require("../../tool_registry-Dkfprsck.js");
+require("../../common-Od8edUXU.js");
+const require_tool = require("../../tool-COSeH8I6.js");
+const require_spooled_markdown_artifact = require("../../spooled_markdown_artifact-RRB113sy.js");
+require("../../guards.cjs");
+let _nhtio_validation = require("@nhtio/validation");
+let simple_statistics = require("simple-statistics");
+//#region src/batteries/tools/statistics/index.ts
+/**
+* Pre-constructed tools for descriptive statistics, correlation, quantiles, and numeric summaries.
+*
+* @module @nhtio/adk/batteries/tools/statistics
+*
+* @remarks
+* Pre-constructed bundled tools for the `statistics` category. Import individually, the whole
+* category, or import every tool via `@nhtio/adk/batteries`.
+*/
+function parseNumbers(input) {
+	let arr = input;
+	if (typeof input === "string") try {
+		arr = JSON.parse(input);
+	} catch {
+		return { error: "Invalid JSON — expected an array of numbers." };
+	}
+	if (!Array.isArray(arr)) return { error: "Input must be a JSON array of numbers." };
+	const nums = arr.filter((v) => typeof v === "number" && Number.isFinite(v));
+	if (nums.length === 0) return { error: "No finite numbers found in the array." };
+	return nums;
+}
+/**
+* Compute descriptive statistics for a JSON array of numbers.
+*
+* @remarks
+* Returns count, sum, min/max/range, mean, median, mode, variance, standard deviation,
+* quartiles (Q1/Q2/Q3), IQR, and key percentiles (P10/P90/P95/P99) as a pretty-printed JSON
+* object. Non-numeric and non-finite entries are silently filtered.
+*/
+var statsDescribeTool = new require_tool.Tool({
+	name: "stats_describe",
+	description: "Compute descriptive statistics for a numeric array: count, sum, min, max, range, mean, median, mode, variance, standard deviation, quartiles (Q1–Q3), IQR, and key percentiles.",
+	inputSchema: _nhtio_validation.validator.object({ numbers: _nhtio_validation.validator.string().required().description("JSON array of numbers") }),
+	artifactConstructor: () => require_spooled_markdown_artifact.SpooledJsonArtifact,
+	handler: async (args) => {
+		const { numbers } = args;
+		const nums = parseNumbers(numbers);
+		if ("error" in nums) return `Error: ${nums.error}`;
+		const sorted = [...nums].sort((a, b) => a - b);
+		const modeVal = (0, simple_statistics.mode)(nums);
+		return JSON.stringify({
+			count: nums.length,
+			sum: Number.parseFloat((0, simple_statistics.sum)(nums).toPrecision(12)),
+			min: (0, simple_statistics.min)(nums),
+			max: (0, simple_statistics.max)(nums),
+			range: (0, simple_statistics.max)(nums) - (0, simple_statistics.min)(nums),
+			mean: Number.parseFloat((0, simple_statistics.mean)(nums).toPrecision(10)),
+			median: (0, simple_statistics.median)(nums),
+			mode: modeVal,
+			variance: Number.parseFloat((0, simple_statistics.variance)(nums).toPrecision(8)),
+			std_dev: Number.parseFloat((0, simple_statistics.standardDeviation)(nums).toPrecision(8)),
+			q1: (0, simple_statistics.quantile)(sorted, .25),
+			q2: (0, simple_statistics.quantile)(sorted, .5),
+			q3: (0, simple_statistics.quantile)(sorted, .75),
+			iqr: (0, simple_statistics.interquartileRange)(nums),
+			p10: (0, simple_statistics.quantile)(sorted, .1),
+			p90: (0, simple_statistics.quantile)(sorted, .9),
+			p95: (0, simple_statistics.quantile)(sorted, .95),
+			p99: (0, simple_statistics.quantile)(sorted, .99)
+		}, null, 2);
+	}
+});
+/**
+* Compute the Pearson correlation coefficient between two numeric arrays.
+*
+* @remarks
+* Returns `r`, `r²` (as a percentage of explained variance), and a plain-English interpretation
+* of strength and direction. Arrays must be the same length and contain at least two points.
+*/
+var statsCorrelateTool = new require_tool.Tool({
+	name: "stats_correlate",
+	description: "Compute the Pearson correlation coefficient between two numeric arrays. Returns the r value (-1 to 1), r², and a plain-English interpretation.",
+	inputSchema: _nhtio_validation.validator.object({
+		x: _nhtio_validation.validator.string().required().description("JSON array of numbers (first variable)"),
+		y: _nhtio_validation.validator.string().required().description("JSON array of numbers (second variable, same length as x)")
+	}),
+	handler: async (args) => {
+		const { x: rawX, y: rawY } = args;
+		const x = parseNumbers(rawX);
+		if ("error" in x) return `Error in x: ${x.error}`;
+		const y = parseNumbers(rawY);
+		if ("error" in y) return `Error in y: ${y.error}`;
+		if (x.length !== y.length) return `Error: Arrays must be the same length (x: ${x.length}, y: ${y.length}).`;
+		if (x.length < 2) return "Error: At least 2 data points required.";
+		try {
+			const r = (0, simple_statistics.sampleCorrelation)(x, y);
+			const absR = Math.abs(r);
+			const direction = r > 0 ? "positive" : r < 0 ? "negative" : "no";
+			const strength = absR >= .9 ? "very strong" : absR >= .7 ? "strong" : absR >= .5 ? "moderate" : absR >= .3 ? "weak" : "very weak / negligible";
+			return `r = ${r.toFixed(6)}\nr² = ${(r * r * 100).toFixed(2)}% (explained variance)\nInterpretation: ${strength} ${direction} correlation`;
+		} catch (err) {
+			return `Error: ${require_tool_registry.isError(err) ? err.message : String(err)}`;
+		}
+	}
+});
+/**
+* Transform a numeric array — normalise, smooth, rank, or detect outliers.
+*
+* @remarks
+* Supported operations: `normalize_min_max`, `normalize_z_score`, `normalize_percent_of_sum`,
+* `running_total`, `rolling_avg`, `pct_change`, `rank`, `outliers_iqr`, `outliers_zscore`. Most
+* operations return a JSON array of transformed values; outlier operations return a
+* human-readable report.
+*/
+var statsTransformTool = new require_tool.Tool({
+	name: "stats_transform",
+	description: "Transform a numeric array: normalize (min-max or z-score), compute running totals, rolling averages, percent change between consecutive values, rank each value, or detect outliers.",
+	inputSchema: _nhtio_validation.validator.object({
+		numbers: _nhtio_validation.validator.string().required().description("JSON array of numbers"),
+		operation: _nhtio_validation.validator.string().valid("normalize_min_max", "normalize_z_score", "normalize_percent_of_sum", "running_total", "rolling_avg", "pct_change", "rank", "outliers_iqr", "outliers_zscore").required().description("Transformation to apply"),
+		window: _nhtio_validation.validator.number().default(3).description("For rolling_avg: window size (default: 3)"),
+		threshold: _nhtio_validation.validator.number().default(3).description("For outliers_zscore: z-score threshold (default: 3.0)")
+	}),
+	handler: async (args) => {
+		const { numbers, operation, window, threshold } = args;
+		const nums = parseNumbers(numbers);
+		if ("error" in nums) return `Error: ${nums.error}`;
+		switch (operation) {
+			case "normalize_min_max": {
+				const lo = (0, simple_statistics.min)(nums);
+				const hi = (0, simple_statistics.max)(nums);
+				if (lo === hi) return JSON.stringify(nums.map(() => 0));
+				return JSON.stringify(nums.map((v) => Number.parseFloat(((v - lo) / (hi - lo)).toFixed(8))));
+			}
+			case "normalize_z_score": {
+				const m = (0, simple_statistics.mean)(nums);
+				const sd = (0, simple_statistics.standardDeviation)(nums);
+				if (sd === 0) return JSON.stringify(nums.map(() => 0));
+				return JSON.stringify(nums.map((v) => Number.parseFloat((0, simple_statistics.zScore)(v, m, sd).toFixed(8))));
+			}
+			case "normalize_percent_of_sum": {
+				const total = (0, simple_statistics.sum)(nums);
+				if (total === 0) return JSON.stringify(nums.map(() => 0));
+				return JSON.stringify(nums.map((v) => Number.parseFloat((v / total * 100).toFixed(4))));
+			}
+			case "running_total": {
+				const totals = [];
+				let acc = 0;
+				for (const v of nums) {
+					acc += v;
+					totals.push(Number.parseFloat(acc.toPrecision(12)));
+				}
+				return JSON.stringify(totals);
+			}
+			case "rolling_avg": {
+				const w = Math.max(1, Math.floor(window));
+				return JSON.stringify(nums.map((_, i) => {
+					const slice = nums.slice(Math.max(0, i - w + 1), i + 1);
+					return Number.parseFloat((0, simple_statistics.mean)(slice).toPrecision(8));
+				}));
+			}
+			case "pct_change": {
+				const changes = [null];
+				for (let i = 1; i < nums.length; i++) if (nums[i - 1] === 0) changes.push(null);
+				else changes.push(Number.parseFloat(((nums[i] - nums[i - 1]) / Math.abs(nums[i - 1]) * 100).toFixed(4)));
+				return JSON.stringify(changes);
+			}
+			case "rank": {
+				const sorted = [...nums].sort((a, b) => a - b);
+				return JSON.stringify(nums.map((v) => sorted.indexOf(v) + 1));
+			}
+			case "outliers_iqr": {
+				const sorted = [...nums].sort((a, b) => a - b);
+				const q1 = (0, simple_statistics.quantile)(sorted, .25);
+				const q3 = (0, simple_statistics.quantile)(sorted, .75);
+				const iqr = q3 - q1;
+				const lo = q1 - 1.5 * iqr;
+				const hi = q3 + 1.5 * iqr;
+				const outliers = nums.map((v, i) => ({
+					index: i,
+					value: v
+				})).filter(({ value }) => value < lo || value > hi);
+				if (outliers.length === 0) return "No outliers detected (IQR method).";
+				return `${outliers.length} outlier(s) detected:\n${outliers.map((o) => `  [${o.index}] = ${o.value}`).join("\n")}`;
+			}
+			case "outliers_zscore": {
+				const m = (0, simple_statistics.mean)(nums);
+				const sd = (0, simple_statistics.standardDeviation)(nums);
+				const outliers = nums.map((v, i) => ({
+					index: i,
+					value: v,
+					z: sd === 0 ? 0 : Math.abs((0, simple_statistics.zScore)(v, m, sd))
+				})).filter((o) => o.z > threshold);
+				if (outliers.length === 0) return `No outliers detected (|z| > ${threshold}).`;
+				return `${outliers.length} outlier(s) detected (|z| > ${threshold}):\n${outliers.map((o) => `  [${o.index}] = ${o.value} (z = ${o.z.toFixed(3)})`).join("\n")}`;
+			}
+			default: return `Error: Unknown operation "${operation}".`;
+		}
+	}
+});
+/**
+* Bin a numeric array into equal-width histogram buckets.
+*
+* @remarks
+* Output is a text histogram showing each bin's range, count, percentage of total, and a bar
+* chart. The last bin is inclusive on both ends; preceding bins are half-open. `bins` is clamped
+* to `[2, 100]`.
+*/
+var statsHistogramTool = new require_tool.Tool({
+	name: "stats_histogram",
+	description: "Bin a numeric array into equal-width histogram buckets and display counts.",
+	inputSchema: _nhtio_validation.validator.object({
+		numbers: _nhtio_validation.validator.string().required().description("JSON array of numbers"),
+		bins: _nhtio_validation.validator.number().default(10).description("Number of bins (default: 10, max: 100)")
+	}),
+	handler: async (args) => {
+		const { numbers, bins } = args;
+		const nums = parseNumbers(numbers);
+		if ("error" in nums) return `Error: ${nums.error}`;
+		const binCount = Math.max(2, Math.min(100, Math.floor(bins)));
+		try {
+			const breaks = (0, simple_statistics.equalIntervalBreaks)(nums, binCount);
+			const rows = [];
+			const maxCount = (() => {
+				let m = 0;
+				for (let i = 0; i < breaks.length - 1; i++) {
+					const isLast = i === breaks.length - 2;
+					const count = nums.filter((v) => isLast ? v >= breaks[i] && v <= breaks[i + 1] : v >= breaks[i] && v < breaks[i + 1]).length;
+					if (count > m) m = count;
+				}
+				return m;
+			})();
+			for (let i = 0; i < breaks.length - 1; i++) {
+				const isLast = i === breaks.length - 2;
+				const count = nums.filter((v) => isLast ? v >= breaks[i] && v <= breaks[i + 1] : v >= breaks[i] && v < breaks[i + 1]).length;
+				const pct = (count / nums.length * 100).toFixed(1);
+				const bar = "█".repeat(maxCount > 0 ? Math.round(count / maxCount * 20) : 0);
+				const range = `[${breaks[i].toPrecision(4)}, ${breaks[i + 1].toPrecision(4)}${isLast ? "]" : ")"}`;
+				rows.push(`${range.padEnd(22)} ${String(count).padStart(4)} (${pct.padStart(5)}%) ${bar}`);
+			}
+			return rows.join("\n");
+		} catch (err) {
+			return `Error: ${require_tool_registry.isError(err) ? err.message : String(err)}`;
+		}
+	}
+});
+//#endregion
+exports.statsCorrelateTool = statsCorrelateTool;
+exports.statsDescribeTool = statsDescribeTool;
+exports.statsHistogramTool = statsHistogramTool;
+exports.statsTransformTool = statsTransformTool;
+
+//# sourceMappingURL=statistics.cjs.map

package/batteries/tools/statistics.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"statistics.cjs","names":[],"sources":["../../../src/batteries/tools/statistics/index.ts"],"sourcesContent":["/**\n * Pre-constructed tools for descriptive statistics, correlation, quantiles, and numeric summaries.\n *\n * @module @nhtio/adk/batteries/tools/statistics\n *\n * @remarks\n * Pre-constructed bundled tools for the `statistics` category. Import individually, the whole\n * category, or import every tool via `@nhtio/adk/batteries`.\n */\n\nimport { isError } from '@nhtio/adk/guards'\nimport { validator } from '@nhtio/validation'\nimport { Tool, SpooledJsonArtifact } from '@nhtio/adk/common'\nimport {\n  equalIntervalBreaks,\n  interquartileRange,\n  max,\n  mean,\n  median,\n  min,\n  mode,\n  quantile,\n  sampleCorrelation,\n  standardDeviation,\n  sum,\n  variance,\n  zScore,\n} from 'simple-statistics'\n\nfunction parseNumbers(input: unknown): number[] | { error: string } {\n  let arr: unknown = input\n  if (typeof input === 'string') {\n    try {\n      arr = JSON.parse(input)\n    } catch {\n      return { error: 'Invalid JSON — expected an array of numbers.' }\n    }\n  }\n  if (!Array.isArray(arr)) return { error: 'Input must be a JSON array of numbers.' }\n  const nums = (arr as unknown[]).filter(\n    (v): v is number => typeof v === 'number' && Number.isFinite(v)\n  )\n  if (nums.length === 0) return { error: 'No finite numbers found in the array.' }\n  return nums\n}\n\n/**\n * Compute descriptive statistics for a JSON array of numbers.\n *\n * @remarks\n * Returns count, sum, min/max/range, mean, median, mode, variance, standard deviation,\n * quartiles (Q1/Q2/Q3), IQR, and key percentiles (P10/P90/P95/P99) as a pretty-printed JSON\n * object. Non-numeric and non-finite entries are silently filtered.\n */\nexport const statsDescribeTool = new Tool({\n  name: 'stats_describe',\n  description:\n    'Compute descriptive statistics for a numeric array: count, sum, min, max, range, mean, median, mode, variance, standard deviation, quartiles (Q1–Q3), IQR, and key percentiles.',\n  inputSchema: validator.object({\n    numbers: validator.string().required().description('JSON array of numbers'),\n  }),\n  artifactConstructor: () => SpooledJsonArtifact,\n  handler: async (args) => {\n    const { numbers } = args as { numbers: string }\n    const nums = parseNumbers(numbers)\n    if ('error' in nums) return `Error: ${nums.error}`\n\n    const sorted = [...nums].sort((a, b) => a - b)\n    const modeVal = mode(nums)\n\n    return JSON.stringify(\n      {\n        count: nums.length,\n        sum: Number.parseFloat(sum(nums).toPrecision(12)),\n        min: min(nums),\n        max: max(nums),\n        range: max(nums) - min(nums),\n        mean: Number.parseFloat(mean(nums).toPrecision(10)),\n        median: median(nums),\n        mode: modeVal,\n        variance: Number.parseFloat(variance(nums).toPrecision(8)),\n        std_dev: Number.parseFloat(standardDeviation(nums).toPrecision(8)),\n        q1: quantile(sorted, 0.25),\n        q2: quantile(sorted, 0.5),\n        q3: quantile(sorted, 0.75),\n        iqr: interquartileRange(nums),\n        p10: quantile(sorted, 0.1),\n        p90: quantile(sorted, 0.9),\n        p95: quantile(sorted, 0.95),\n        p99: quantile(sorted, 0.99),\n      },\n      null,\n      2\n    )\n  },\n})\n\n/**\n * Compute the Pearson correlation coefficient between two numeric arrays.\n *\n * @remarks\n * Returns `r`, `r²` (as a percentage of explained variance), and a plain-English interpretation\n * of strength and direction. Arrays must be the same length and contain at least two points.\n */\nexport const statsCorrelateTool = new Tool({\n  name: 'stats_correlate',\n  description:\n    'Compute the Pearson correlation coefficient between two numeric arrays. Returns the r value (-1 to 1), r², and a plain-English interpretation.',\n  inputSchema: validator.object({\n    x: validator.string().required().description('JSON array of numbers (first variable)'),\n    y: validator\n      .string()\n      .required()\n      .description('JSON array of numbers (second variable, same length as x)'),\n  }),\n  handler: async (args) => {\n    const { x: rawX, y: rawY } = args as { x: string; y: string }\n    const x = parseNumbers(rawX)\n    if ('error' in x) return `Error in x: ${x.error}`\n    const y = parseNumbers(rawY)\n    if ('error' in y) return `Error in y: ${y.error}`\n\n    if (x.length !== y.length)\n      return `Error: Arrays must be the same length (x: ${x.length}, y: ${y.length}).`\n    if (x.length < 2) return 'Error: At least 2 data points required.'\n\n    try {\n      const r = sampleCorrelation(x, y)\n      const absR = Math.abs(r)\n      const direction = r > 0 ? 'positive' : r < 0 ? 'negative' : 'no'\n      const strength =\n        absR >= 0.9\n          ? 'very strong'\n          : absR >= 0.7\n            ? 'strong'\n            : absR >= 0.5\n              ? 'moderate'\n              : absR >= 0.3\n                ? 'weak'\n                : 'very weak / negligible'\n      return `r = ${r.toFixed(6)}\\nr² = ${(r * r * 100).toFixed(2)}% (explained variance)\\nInterpretation: ${strength} ${direction} correlation`\n    } catch (err) {\n      return `Error: ${isError(err) ? err.message : String(err)}`\n    }\n  },\n})\n\n/**\n * Transform a numeric array — normalise, smooth, rank, or detect outliers.\n *\n * @remarks\n * Supported operations: `normalize_min_max`, `normalize_z_score`, `normalize_percent_of_sum`,\n * `running_total`, `rolling_avg`, `pct_change`, `rank`, `outliers_iqr`, `outliers_zscore`. Most\n * operations return a JSON array of transformed values; outlier operations return a\n * human-readable report.\n */\nexport const statsTransformTool = new Tool({\n  name: 'stats_transform',\n  description:\n    'Transform a numeric array: normalize (min-max or z-score), compute running totals, rolling averages, percent change between consecutive values, rank each value, or detect outliers.',\n  inputSchema: validator.object({\n    numbers: validator.string().required().description('JSON array of numbers'),\n    operation: validator\n      .string()\n      .valid(\n        'normalize_min_max',\n        'normalize_z_score',\n        'normalize_percent_of_sum',\n        'running_total',\n        'rolling_avg',\n        'pct_change',\n        'rank',\n        'outliers_iqr',\n        'outliers_zscore'\n      )\n      .required()\n      .description('Transformation to apply'),\n    window: validator.number().default(3).description('For rolling_avg: window size (default: 3)'),\n    threshold: validator\n      .number()\n      .default(3.0)\n      .description('For outliers_zscore: z-score threshold (default: 3.0)'),\n  }),\n  handler: async (args) => {\n    const { numbers, operation, window, threshold } = args as {\n      numbers: string\n      operation: string\n      window: number\n      threshold: number\n    }\n    const nums = parseNumbers(numbers)\n    if ('error' in nums) return `Error: ${nums.error}`\n\n    switch (operation) {\n      case 'normalize_min_max': {\n        const lo = min(nums)\n        const hi = max(nums)\n        if (lo === hi) return JSON.stringify(nums.map(() => 0))\n        return JSON.stringify(nums.map((v) => Number.parseFloat(((v - lo) / (hi - lo)).toFixed(8))))\n      }\n\n      case 'normalize_z_score': {\n        const m = mean(nums)\n        const sd = standardDeviation(nums)\n        if (sd === 0) return JSON.stringify(nums.map(() => 0))\n        return JSON.stringify(nums.map((v) => Number.parseFloat(zScore(v, m, sd).toFixed(8))))\n      }\n\n      case 'normalize_percent_of_sum': {\n        const total = sum(nums)\n        if (total === 0) return JSON.stringify(nums.map(() => 0))\n        return JSON.stringify(nums.map((v) => Number.parseFloat(((v / total) * 100).toFixed(4))))\n      }\n\n      case 'running_total': {\n        const totals: number[] = []\n        let acc = 0\n        for (const v of nums) {\n          acc += v\n          totals.push(Number.parseFloat(acc.toPrecision(12)))\n        }\n        return JSON.stringify(totals)\n      }\n\n      case 'rolling_avg': {\n        const w = Math.max(1, Math.floor(window))\n        return JSON.stringify(\n          nums.map((_, i) => {\n            const slice = nums.slice(Math.max(0, i - w + 1), i + 1)\n            return Number.parseFloat(mean(slice).toPrecision(8))\n          })\n        )\n      }\n\n      case 'pct_change': {\n        const changes: (number | null)[] = [null]\n        for (let i = 1; i < nums.length; i++) {\n          if (nums[i - 1] === 0) {\n            changes.push(null)\n          } else {\n            changes.push(\n              Number.parseFloat(\n                (((nums[i] - nums[i - 1]) / Math.abs(nums[i - 1])) * 100).toFixed(4)\n              )\n            )\n          }\n        }\n        return JSON.stringify(changes)\n      }\n\n      case 'rank': {\n        const sorted = [...nums].sort((a, b) => a - b)\n        return JSON.stringify(nums.map((v) => sorted.indexOf(v) + 1))\n      }\n\n      case 'outliers_iqr': {\n        const sorted = [...nums].sort((a, b) => a - b)\n        const q1 = quantile(sorted, 0.25)\n        const q3 = quantile(sorted, 0.75)\n        const iqr = q3 - q1\n        const lo = q1 - 1.5 * iqr\n        const hi = q3 + 1.5 * iqr\n        const outliers = nums\n          .map((v, i) => ({ index: i, value: v }))\n          .filter(({ value }) => value < lo || value > hi)\n        if (outliers.length === 0) return 'No outliers detected (IQR method).'\n        return `${outliers.length} outlier(s) detected:\\n${outliers.map((o) => `  [${o.index}] = ${o.value}`).join('\\n')}`\n      }\n\n      case 'outliers_zscore': {\n        const m = mean(nums)\n        const sd = standardDeviation(nums)\n        const outliers = nums\n          .map((v, i) => ({ index: i, value: v, z: sd === 0 ? 0 : Math.abs(zScore(v, m, sd)) }))\n          .filter((o) => o.z > threshold)\n        if (outliers.length === 0) return `No outliers detected (|z| > ${threshold}).`\n        return `${outliers.length} outlier(s) detected (|z| > ${threshold}):\\n${outliers.map((o) => `  [${o.index}] = ${o.value} (z = ${o.z.toFixed(3)})`).join('\\n')}`\n      }\n\n      default:\n        return `Error: Unknown operation \"${operation}\".`\n    }\n  },\n})\n\n/**\n * Bin a numeric array into equal-width histogram buckets.\n *\n * @remarks\n * Output is a text histogram showing each bin's range, count, percentage of total, and a bar\n * chart. The last bin is inclusive on both ends; preceding bins are half-open. `bins` is clamped\n * to `[2, 100]`.\n */\nexport const statsHistogramTool = new Tool({\n  name: 'stats_histogram',\n  description: 'Bin a numeric array into equal-width histogram buckets and display counts.',\n  inputSchema: validator.object({\n    numbers: validator.string().required().description('JSON array of numbers'),\n    bins: validator.number().default(10).description('Number of bins (default: 10, max: 100)'),\n  }),\n  handler: async (args) => {\n    const { numbers, bins } = args as { numbers: string; bins: number }\n    const nums = parseNumbers(numbers)\n    if ('error' in nums) return `Error: ${nums.error}`\n\n    const binCount = Math.max(2, Math.min(100, Math.floor(bins)))\n\n    try {\n      const breaks = equalIntervalBreaks(nums, binCount)\n      const rows: string[] = []\n      const maxCount = (() => {\n        let m = 0\n        for (let i = 0; i < breaks.length - 1; i++) {\n          const isLast = i === breaks.length - 2\n          const count = nums.filter((v) =>\n            isLast ? v >= breaks[i] && v <= breaks[i + 1] : v >= breaks[i] && v < breaks[i + 1]\n          ).length\n          if (count > m) m = count\n        }\n        return m\n      })()\n\n      for (let i = 0; i < breaks.length - 1; i++) {\n        const isLast = i === breaks.length - 2\n        const count = nums.filter((v) =>\n          isLast ? v >= breaks[i] && v <= breaks[i + 1] : v >= breaks[i] && v < breaks[i + 1]\n        ).length\n        const pct = ((count / nums.length) * 100).toFixed(1)\n        const bar = '█'.repeat(maxCount > 0 ? Math.round((count / maxCount) * 20) : 0)\n        const range = `[${breaks[i].toPrecision(4)}, ${breaks[i + 1].toPrecision(4)}${isLast ? ']' : ')'}`\n        rows.push(`${range.padEnd(22)} ${String(count).padStart(4)} (${pct.padStart(5)}%) ${bar}`)\n      }\n\n      return rows.join('\\n')\n    } catch (err) {\n      return `Error: ${isError(err) ? err.message : String(err)}`\n    }\n  },\n})\n"],"mappings":"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"}

package/batteries/tools/statistics.mjs

@@ -0,0 +1,248 @@
+import { o as isError } from "../../tool_registry-DqLOyGyG.mjs";
+import "../../common-DeZaonK1.mjs";
+import { t as Tool } from "../../tool-D2WB1EA1.mjs";
+import { n as SpooledJsonArtifact } from "../../spooled_markdown_artifact-BpUJol0W.mjs";
+import "../../guards.mjs";
+import { validator } from "@nhtio/validation";
+import { equalIntervalBreaks, interquartileRange, max, mean, median, min, mode, quantile, sampleCorrelation, standardDeviation, sum, variance, zScore } from "simple-statistics";
+//#region src/batteries/tools/statistics/index.ts
+/**
+* Pre-constructed tools for descriptive statistics, correlation, quantiles, and numeric summaries.
+*
+* @module @nhtio/adk/batteries/tools/statistics
+*
+* @remarks
+* Pre-constructed bundled tools for the `statistics` category. Import individually, the whole
+* category, or import every tool via `@nhtio/adk/batteries`.
+*/
+function parseNumbers(input) {
+	let arr = input;
+	if (typeof input === "string") try {
+		arr = JSON.parse(input);
+	} catch {
+		return { error: "Invalid JSON — expected an array of numbers." };
+	}
+	if (!Array.isArray(arr)) return { error: "Input must be a JSON array of numbers." };
+	const nums = arr.filter((v) => typeof v === "number" && Number.isFinite(v));
+	if (nums.length === 0) return { error: "No finite numbers found in the array." };
+	return nums;
+}
+/**
+* Compute descriptive statistics for a JSON array of numbers.
+*
+* @remarks
+* Returns count, sum, min/max/range, mean, median, mode, variance, standard deviation,
+* quartiles (Q1/Q2/Q3), IQR, and key percentiles (P10/P90/P95/P99) as a pretty-printed JSON
+* object. Non-numeric and non-finite entries are silently filtered.
+*/
+var statsDescribeTool = new Tool({
+	name: "stats_describe",
+	description: "Compute descriptive statistics for a numeric array: count, sum, min, max, range, mean, median, mode, variance, standard deviation, quartiles (Q1–Q3), IQR, and key percentiles.",
+	inputSchema: validator.object({ numbers: validator.string().required().description("JSON array of numbers") }),
+	artifactConstructor: () => SpooledJsonArtifact,
+	handler: async (args) => {
+		const { numbers } = args;
+		const nums = parseNumbers(numbers);
+		if ("error" in nums) return `Error: ${nums.error}`;
+		const sorted = [...nums].sort((a, b) => a - b);
+		const modeVal = mode(nums);
+		return JSON.stringify({
+			count: nums.length,
+			sum: Number.parseFloat(sum(nums).toPrecision(12)),
+			min: min(nums),
+			max: max(nums),
+			range: max(nums) - min(nums),
+			mean: Number.parseFloat(mean(nums).toPrecision(10)),
+			median: median(nums),
+			mode: modeVal,
+			variance: Number.parseFloat(variance(nums).toPrecision(8)),
+			std_dev: Number.parseFloat(standardDeviation(nums).toPrecision(8)),
+			q1: quantile(sorted, .25),
+			q2: quantile(sorted, .5),
+			q3: quantile(sorted, .75),
+			iqr: interquartileRange(nums),
+			p10: quantile(sorted, .1),
+			p90: quantile(sorted, .9),
+			p95: quantile(sorted, .95),
+			p99: quantile(sorted, .99)
+		}, null, 2);
+	}
+});
+/**
+* Compute the Pearson correlation coefficient between two numeric arrays.
+*
+* @remarks
+* Returns `r`, `r²` (as a percentage of explained variance), and a plain-English interpretation
+* of strength and direction. Arrays must be the same length and contain at least two points.
+*/
+var statsCorrelateTool = new Tool({
+	name: "stats_correlate",
+	description: "Compute the Pearson correlation coefficient between two numeric arrays. Returns the r value (-1 to 1), r², and a plain-English interpretation.",
+	inputSchema: validator.object({
+		x: validator.string().required().description("JSON array of numbers (first variable)"),
+		y: validator.string().required().description("JSON array of numbers (second variable, same length as x)")
+	}),
+	handler: async (args) => {
+		const { x: rawX, y: rawY } = args;
+		const x = parseNumbers(rawX);
+		if ("error" in x) return `Error in x: ${x.error}`;
+		const y = parseNumbers(rawY);
+		if ("error" in y) return `Error in y: ${y.error}`;
+		if (x.length !== y.length) return `Error: Arrays must be the same length (x: ${x.length}, y: ${y.length}).`;
+		if (x.length < 2) return "Error: At least 2 data points required.";
+		try {
+			const r = sampleCorrelation(x, y);
+			const absR = Math.abs(r);
+			const direction = r > 0 ? "positive" : r < 0 ? "negative" : "no";
+			const strength = absR >= .9 ? "very strong" : absR >= .7 ? "strong" : absR >= .5 ? "moderate" : absR >= .3 ? "weak" : "very weak / negligible";
+			return `r = ${r.toFixed(6)}\nr² = ${(r * r * 100).toFixed(2)}% (explained variance)\nInterpretation: ${strength} ${direction} correlation`;
+		} catch (err) {
+			return `Error: ${isError(err) ? err.message : String(err)}`;
+		}
+	}
+});
+/**
+* Transform a numeric array — normalise, smooth, rank, or detect outliers.
+*
+* @remarks
+* Supported operations: `normalize_min_max`, `normalize_z_score`, `normalize_percent_of_sum`,
+* `running_total`, `rolling_avg`, `pct_change`, `rank`, `outliers_iqr`, `outliers_zscore`. Most
+* operations return a JSON array of transformed values; outlier operations return a
+* human-readable report.
+*/
+var statsTransformTool = new Tool({
+	name: "stats_transform",
+	description: "Transform a numeric array: normalize (min-max or z-score), compute running totals, rolling averages, percent change between consecutive values, rank each value, or detect outliers.",
+	inputSchema: validator.object({
+		numbers: validator.string().required().description("JSON array of numbers"),
+		operation: validator.string().valid("normalize_min_max", "normalize_z_score", "normalize_percent_of_sum", "running_total", "rolling_avg", "pct_change", "rank", "outliers_iqr", "outliers_zscore").required().description("Transformation to apply"),
+		window: validator.number().default(3).description("For rolling_avg: window size (default: 3)"),
+		threshold: validator.number().default(3).description("For outliers_zscore: z-score threshold (default: 3.0)")
+	}),
+	handler: async (args) => {
+		const { numbers, operation, window, threshold } = args;
+		const nums = parseNumbers(numbers);
+		if ("error" in nums) return `Error: ${nums.error}`;
+		switch (operation) {
+			case "normalize_min_max": {
+				const lo = min(nums);
+				const hi = max(nums);
+				if (lo === hi) return JSON.stringify(nums.map(() => 0));
+				return JSON.stringify(nums.map((v) => Number.parseFloat(((v - lo) / (hi - lo)).toFixed(8))));
+			}
+			case "normalize_z_score": {
+				const m = mean(nums);
+				const sd = standardDeviation(nums);
+				if (sd === 0) return JSON.stringify(nums.map(() => 0));
+				return JSON.stringify(nums.map((v) => Number.parseFloat(zScore(v, m, sd).toFixed(8))));
+			}
+			case "normalize_percent_of_sum": {
+				const total = sum(nums);
+				if (total === 0) return JSON.stringify(nums.map(() => 0));
+				return JSON.stringify(nums.map((v) => Number.parseFloat((v / total * 100).toFixed(4))));
+			}
+			case "running_total": {
+				const totals = [];
+				let acc = 0;
+				for (const v of nums) {
+					acc += v;
+					totals.push(Number.parseFloat(acc.toPrecision(12)));
+				}
+				return JSON.stringify(totals);
+			}
+			case "rolling_avg": {
+				const w = Math.max(1, Math.floor(window));
+				return JSON.stringify(nums.map((_, i) => {
+					const slice = nums.slice(Math.max(0, i - w + 1), i + 1);
+					return Number.parseFloat(mean(slice).toPrecision(8));
+				}));
+			}
+			case "pct_change": {
+				const changes = [null];
+				for (let i = 1; i < nums.length; i++) if (nums[i - 1] === 0) changes.push(null);
+				else changes.push(Number.parseFloat(((nums[i] - nums[i - 1]) / Math.abs(nums[i - 1]) * 100).toFixed(4)));
+				return JSON.stringify(changes);
+			}
+			case "rank": {
+				const sorted = [...nums].sort((a, b) => a - b);
+				return JSON.stringify(nums.map((v) => sorted.indexOf(v) + 1));
+			}
+			case "outliers_iqr": {
+				const sorted = [...nums].sort((a, b) => a - b);
+				const q1 = quantile(sorted, .25);
+				const q3 = quantile(sorted, .75);
+				const iqr = q3 - q1;
+				const lo = q1 - 1.5 * iqr;
+				const hi = q3 + 1.5 * iqr;
+				const outliers = nums.map((v, i) => ({
+					index: i,
+					value: v
+				})).filter(({ value }) => value < lo || value > hi);
+				if (outliers.length === 0) return "No outliers detected (IQR method).";
+				return `${outliers.length} outlier(s) detected:\n${outliers.map((o) => `  [${o.index}] = ${o.value}`).join("\n")}`;
+			}
+			case "outliers_zscore": {
+				const m = mean(nums);
+				const sd = standardDeviation(nums);
+				const outliers = nums.map((v, i) => ({
+					index: i,
+					value: v,
+					z: sd === 0 ? 0 : Math.abs(zScore(v, m, sd))
+				})).filter((o) => o.z > threshold);
+				if (outliers.length === 0) return `No outliers detected (|z| > ${threshold}).`;
+				return `${outliers.length} outlier(s) detected (|z| > ${threshold}):\n${outliers.map((o) => `  [${o.index}] = ${o.value} (z = ${o.z.toFixed(3)})`).join("\n")}`;
+			}
+			default: return `Error: Unknown operation "${operation}".`;
+		}
+	}
+});
+/**
+* Bin a numeric array into equal-width histogram buckets.
+*
+* @remarks
+* Output is a text histogram showing each bin's range, count, percentage of total, and a bar
+* chart. The last bin is inclusive on both ends; preceding bins are half-open. `bins` is clamped
+* to `[2, 100]`.
+*/
+var statsHistogramTool = new Tool({
+	name: "stats_histogram",
+	description: "Bin a numeric array into equal-width histogram buckets and display counts.",
+	inputSchema: validator.object({
+		numbers: validator.string().required().description("JSON array of numbers"),
+		bins: validator.number().default(10).description("Number of bins (default: 10, max: 100)")
+	}),
+	handler: async (args) => {
+		const { numbers, bins } = args;
+		const nums = parseNumbers(numbers);
+		if ("error" in nums) return `Error: ${nums.error}`;
+		const binCount = Math.max(2, Math.min(100, Math.floor(bins)));
+		try {
+			const breaks = equalIntervalBreaks(nums, binCount);
+			const rows = [];
+			const maxCount = (() => {
+				let m = 0;
+				for (let i = 0; i < breaks.length - 1; i++) {
+					const isLast = i === breaks.length - 2;
+					const count = nums.filter((v) => isLast ? v >= breaks[i] && v <= breaks[i + 1] : v >= breaks[i] && v < breaks[i + 1]).length;
+					if (count > m) m = count;
+				}
+				return m;
+			})();
+			for (let i = 0; i < breaks.length - 1; i++) {
+				const isLast = i === breaks.length - 2;
+				const count = nums.filter((v) => isLast ? v >= breaks[i] && v <= breaks[i + 1] : v >= breaks[i] && v < breaks[i + 1]).length;
+				const pct = (count / nums.length * 100).toFixed(1);
+				const bar = "█".repeat(maxCount > 0 ? Math.round(count / maxCount * 20) : 0);
+				const range = `[${breaks[i].toPrecision(4)}, ${breaks[i + 1].toPrecision(4)}${isLast ? "]" : ")"}`;
+				rows.push(`${range.padEnd(22)} ${String(count).padStart(4)} (${pct.padStart(5)}%) ${bar}`);
+			}
+			return rows.join("\n");
+		} catch (err) {
+			return `Error: ${isError(err) ? err.message : String(err)}`;
+		}
+	}
+});
+//#endregion
+export { statsCorrelateTool, statsDescribeTool, statsHistogramTool, statsTransformTool };
+
+//# sourceMappingURL=statistics.mjs.map

package/batteries/tools/statistics.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"statistics.mjs","names":[],"sources":["../../../src/batteries/tools/statistics/index.ts"],"sourcesContent":["/**\n * Pre-constructed tools for descriptive statistics, correlation, quantiles, and numeric summaries.\n *\n * @module @nhtio/adk/batteries/tools/statistics\n *\n * @remarks\n * Pre-constructed bundled tools for the `statistics` category. Import individually, the whole\n * category, or import every tool via `@nhtio/adk/batteries`.\n */\n\nimport { isError } from '@nhtio/adk/guards'\nimport { validator } from '@nhtio/validation'\nimport { Tool, SpooledJsonArtifact } from '@nhtio/adk/common'\nimport {\n  equalIntervalBreaks,\n  interquartileRange,\n  max,\n  mean,\n  median,\n  min,\n  mode,\n  quantile,\n  sampleCorrelation,\n  standardDeviation,\n  sum,\n  variance,\n  zScore,\n} from 'simple-statistics'\n\nfunction parseNumbers(input: unknown): number[] | { error: string } {\n  let arr: unknown = input\n  if (typeof input === 'string') {\n    try {\n      arr = JSON.parse(input)\n    } catch {\n      return { error: 'Invalid JSON — expected an array of numbers.' }\n    }\n  }\n  if (!Array.isArray(arr)) return { error: 'Input must be a JSON array of numbers.' }\n  const nums = (arr as unknown[]).filter(\n    (v): v is number => typeof v === 'number' && Number.isFinite(v)\n  )\n  if (nums.length === 0) return { error: 'No finite numbers found in the array.' }\n  return nums\n}\n\n/**\n * Compute descriptive statistics for a JSON array of numbers.\n *\n * @remarks\n * Returns count, sum, min/max/range, mean, median, mode, variance, standard deviation,\n * quartiles (Q1/Q2/Q3), IQR, and key percentiles (P10/P90/P95/P99) as a pretty-printed JSON\n * object. Non-numeric and non-finite entries are silently filtered.\n */\nexport const statsDescribeTool = new Tool({\n  name: 'stats_describe',\n  description:\n    'Compute descriptive statistics for a numeric array: count, sum, min, max, range, mean, median, mode, variance, standard deviation, quartiles (Q1–Q3), IQR, and key percentiles.',\n  inputSchema: validator.object({\n    numbers: validator.string().required().description('JSON array of numbers'),\n  }),\n  artifactConstructor: () => SpooledJsonArtifact,\n  handler: async (args) => {\n    const { numbers } = args as { numbers: string }\n    const nums = parseNumbers(numbers)\n    if ('error' in nums) return `Error: ${nums.error}`\n\n    const sorted = [...nums].sort((a, b) => a - b)\n    const modeVal = mode(nums)\n\n    return JSON.stringify(\n      {\n        count: nums.length,\n        sum: Number.parseFloat(sum(nums).toPrecision(12)),\n        min: min(nums),\n        max: max(nums),\n        range: max(nums) - min(nums),\n        mean: Number.parseFloat(mean(nums).toPrecision(10)),\n        median: median(nums),\n        mode: modeVal,\n        variance: Number.parseFloat(variance(nums).toPrecision(8)),\n        std_dev: Number.parseFloat(standardDeviation(nums).toPrecision(8)),\n        q1: quantile(sorted, 0.25),\n        q2: quantile(sorted, 0.5),\n        q3: quantile(sorted, 0.75),\n        iqr: interquartileRange(nums),\n        p10: quantile(sorted, 0.1),\n        p90: quantile(sorted, 0.9),\n        p95: quantile(sorted, 0.95),\n        p99: quantile(sorted, 0.99),\n      },\n      null,\n      2\n    )\n  },\n})\n\n/**\n * Compute the Pearson correlation coefficient between two numeric arrays.\n *\n * @remarks\n * Returns `r`, `r²` (as a percentage of explained variance), and a plain-English interpretation\n * of strength and direction. Arrays must be the same length and contain at least two points.\n */\nexport const statsCorrelateTool = new Tool({\n  name: 'stats_correlate',\n  description:\n    'Compute the Pearson correlation coefficient between two numeric arrays. Returns the r value (-1 to 1), r², and a plain-English interpretation.',\n  inputSchema: validator.object({\n    x: validator.string().required().description('JSON array of numbers (first variable)'),\n    y: validator\n      .string()\n      .required()\n      .description('JSON array of numbers (second variable, same length as x)'),\n  }),\n  handler: async (args) => {\n    const { x: rawX, y: rawY } = args as { x: string; y: string }\n    const x = parseNumbers(rawX)\n    if ('error' in x) return `Error in x: ${x.error}`\n    const y = parseNumbers(rawY)\n    if ('error' in y) return `Error in y: ${y.error}`\n\n    if (x.length !== y.length)\n      return `Error: Arrays must be the same length (x: ${x.length}, y: ${y.length}).`\n    if (x.length < 2) return 'Error: At least 2 data points required.'\n\n    try {\n      const r = sampleCorrelation(x, y)\n      const absR = Math.abs(r)\n      const direction = r > 0 ? 'positive' : r < 0 ? 'negative' : 'no'\n      const strength =\n        absR >= 0.9\n          ? 'very strong'\n          : absR >= 0.7\n            ? 'strong'\n            : absR >= 0.5\n              ? 'moderate'\n              : absR >= 0.3\n                ? 'weak'\n                : 'very weak / negligible'\n      return `r = ${r.toFixed(6)}\\nr² = ${(r * r * 100).toFixed(2)}% (explained variance)\\nInterpretation: ${strength} ${direction} correlation`\n    } catch (err) {\n      return `Error: ${isError(err) ? err.message : String(err)}`\n    }\n  },\n})\n\n/**\n * Transform a numeric array — normalise, smooth, rank, or detect outliers.\n *\n * @remarks\n * Supported operations: `normalize_min_max`, `normalize_z_score`, `normalize_percent_of_sum`,\n * `running_total`, `rolling_avg`, `pct_change`, `rank`, `outliers_iqr`, `outliers_zscore`. Most\n * operations return a JSON array of transformed values; outlier operations return a\n * human-readable report.\n */\nexport const statsTransformTool = new Tool({\n  name: 'stats_transform',\n  description:\n    'Transform a numeric array: normalize (min-max or z-score), compute running totals, rolling averages, percent change between consecutive values, rank each value, or detect outliers.',\n  inputSchema: validator.object({\n    numbers: validator.string().required().description('JSON array of numbers'),\n    operation: validator\n      .string()\n      .valid(\n        'normalize_min_max',\n        'normalize_z_score',\n        'normalize_percent_of_sum',\n        'running_total',\n        'rolling_avg',\n        'pct_change',\n        'rank',\n        'outliers_iqr',\n        'outliers_zscore'\n      )\n      .required()\n      .description('Transformation to apply'),\n    window: validator.number().default(3).description('For rolling_avg: window size (default: 3)'),\n    threshold: validator\n      .number()\n      .default(3.0)\n      .description('For outliers_zscore: z-score threshold (default: 3.0)'),\n  }),\n  handler: async (args) => {\n    const { numbers, operation, window, threshold } = args as {\n      numbers: string\n      operation: string\n      window: number\n      threshold: number\n    }\n    const nums = parseNumbers(numbers)\n    if ('error' in nums) return `Error: ${nums.error}`\n\n    switch (operation) {\n      case 'normalize_min_max': {\n        const lo = min(nums)\n        const hi = max(nums)\n        if (lo === hi) return JSON.stringify(nums.map(() => 0))\n        return JSON.stringify(nums.map((v) => Number.parseFloat(((v - lo) / (hi - lo)).toFixed(8))))\n      }\n\n      case 'normalize_z_score': {\n        const m = mean(nums)\n        const sd = standardDeviation(nums)\n        if (sd === 0) return JSON.stringify(nums.map(() => 0))\n        return JSON.stringify(nums.map((v) => Number.parseFloat(zScore(v, m, sd).toFixed(8))))\n      }\n\n      case 'normalize_percent_of_sum': {\n        const total = sum(nums)\n        if (total === 0) return JSON.stringify(nums.map(() => 0))\n        return JSON.stringify(nums.map((v) => Number.parseFloat(((v / total) * 100).toFixed(4))))\n      }\n\n      case 'running_total': {\n        const totals: number[] = []\n        let acc = 0\n        for (const v of nums) {\n          acc += v\n          totals.push(Number.parseFloat(acc.toPrecision(12)))\n        }\n        return JSON.stringify(totals)\n      }\n\n      case 'rolling_avg': {\n        const w = Math.max(1, Math.floor(window))\n        return JSON.stringify(\n          nums.map((_, i) => {\n            const slice = nums.slice(Math.max(0, i - w + 1), i + 1)\n            return Number.parseFloat(mean(slice).toPrecision(8))\n          })\n        )\n      }\n\n      case 'pct_change': {\n        const changes: (number | null)[] = [null]\n        for (let i = 1; i < nums.length; i++) {\n          if (nums[i - 1] === 0) {\n            changes.push(null)\n          } else {\n            changes.push(\n              Number.parseFloat(\n                (((nums[i] - nums[i - 1]) / Math.abs(nums[i - 1])) * 100).toFixed(4)\n              )\n            )\n          }\n        }\n        return JSON.stringify(changes)\n      }\n\n      case 'rank': {\n        const sorted = [...nums].sort((a, b) => a - b)\n        return JSON.stringify(nums.map((v) => sorted.indexOf(v) + 1))\n      }\n\n      case 'outliers_iqr': {\n        const sorted = [...nums].sort((a, b) => a - b)\n        const q1 = quantile(sorted, 0.25)\n        const q3 = quantile(sorted, 0.75)\n        const iqr = q3 - q1\n        const lo = q1 - 1.5 * iqr\n        const hi = q3 + 1.5 * iqr\n        const outliers = nums\n          .map((v, i) => ({ index: i, value: v }))\n          .filter(({ value }) => value < lo || value > hi)\n        if (outliers.length === 0) return 'No outliers detected (IQR method).'\n        return `${outliers.length} outlier(s) detected:\\n${outliers.map((o) => `  [${o.index}] = ${o.value}`).join('\\n')}`\n      }\n\n      case 'outliers_zscore': {\n        const m = mean(nums)\n        const sd = standardDeviation(nums)\n        const outliers = nums\n          .map((v, i) => ({ index: i, value: v, z: sd === 0 ? 0 : Math.abs(zScore(v, m, sd)) }))\n          .filter((o) => o.z > threshold)\n        if (outliers.length === 0) return `No outliers detected (|z| > ${threshold}).`\n        return `${outliers.length} outlier(s) detected (|z| > ${threshold}):\\n${outliers.map((o) => `  [${o.index}] = ${o.value} (z = ${o.z.toFixed(3)})`).join('\\n')}`\n      }\n\n      default:\n        return `Error: Unknown operation \"${operation}\".`\n    }\n  },\n})\n\n/**\n * Bin a numeric array into equal-width histogram buckets.\n *\n * @remarks\n * Output is a text histogram showing each bin's range, count, percentage of total, and a bar\n * chart. The last bin is inclusive on both ends; preceding bins are half-open. `bins` is clamped\n * to `[2, 100]`.\n */\nexport const statsHistogramTool = new Tool({\n  name: 'stats_histogram',\n  description: 'Bin a numeric array into equal-width histogram buckets and display counts.',\n  inputSchema: validator.object({\n    numbers: validator.string().required().description('JSON array of numbers'),\n    bins: validator.number().default(10).description('Number of bins (default: 10, max: 100)'),\n  }),\n  handler: async (args) => {\n    const { numbers, bins } = args as { numbers: string; bins: number }\n    const nums = parseNumbers(numbers)\n    if ('error' in nums) return `Error: ${nums.error}`\n\n    const binCount = Math.max(2, Math.min(100, Math.floor(bins)))\n\n    try {\n      const breaks = equalIntervalBreaks(nums, binCount)\n      const rows: string[] = []\n      const maxCount = (() => {\n        let m = 0\n        for (let i = 0; i < breaks.length - 1; i++) {\n          const isLast = i === breaks.length - 2\n          const count = nums.filter((v) =>\n            isLast ? v >= breaks[i] && v <= breaks[i + 1] : v >= breaks[i] && v < breaks[i + 1]\n          ).length\n          if (count > m) m = count\n        }\n        return m\n      })()\n\n      for (let i = 0; i < breaks.length - 1; i++) {\n        const isLast = i === breaks.length - 2\n        const count = nums.filter((v) =>\n          isLast ? v >= breaks[i] && v <= breaks[i + 1] : v >= breaks[i] && v < breaks[i + 1]\n        ).length\n        const pct = ((count / nums.length) * 100).toFixed(1)\n        const bar = '█'.repeat(maxCount > 0 ? Math.round((count / maxCount) * 20) : 0)\n        const range = `[${breaks[i].toPrecision(4)}, ${breaks[i + 1].toPrecision(4)}${isLast ? ']' : ')'}`\n        rows.push(`${range.padEnd(22)} ${String(count).padStart(4)} (${pct.padStart(5)}%) ${bar}`)\n      }\n\n      return rows.join('\\n')\n    } catch (err) {\n      return `Error: ${isError(err) ? err.message : String(err)}`\n    }\n  },\n})\n"],"mappings":";;;;;;;;;;;;;;;;;AA6BA,SAAS,aAAa,OAA8C;CAClE,IAAI,MAAe;CACnB,IAAI,OAAO,UAAU,UACnB,IAAI;EACF,MAAM,KAAK,MAAM,KAAK;CACxB,QAAQ;EACN,OAAO,EAAE,OAAO,+CAA+C;CACjE;CAEF,IAAI,CAAC,MAAM,QAAQ,GAAG,GAAG,OAAO,EAAE,OAAO,yCAAyC;CAClF,MAAM,OAAQ,IAAkB,QAC7B,MAAmB,OAAO,MAAM,YAAY,OAAO,SAAS,CAAC,CAChE;CACA,IAAI,KAAK,WAAW,GAAG,OAAO,EAAE,OAAO,wCAAwC;CAC/E,OAAO;AACT;;;;;;;;;AAUA,IAAa,oBAAoB,IAAI,KAAK;CACxC,MAAM;CACN,aACE;CACF,aAAa,UAAU,OAAO,EAC5B,SAAS,UAAU,OAAO,EAAE,SAAS,EAAE,YAAY,uBAAuB,EAC5E,CAAC;CACD,2BAA2B;CAC3B,SAAS,OAAO,SAAS;EACvB,MAAM,EAAE,YAAY;EACpB,MAAM,OAAO,aAAa,OAAO;EACjC,IAAI,WAAW,MAAM,OAAO,UAAU,KAAK;EAE3C,MAAM,SAAS,CAAC,GAAG,IAAI,EAAE,MAAM,GAAG,MAAM,IAAI,CAAC;EAC7C,MAAM,UAAU,KAAK,IAAI;EAEzB,OAAO,KAAK,UACV;GACE,OAAO,KAAK;GACZ,KAAK,OAAO,WAAW,IAAI,IAAI,EAAE,YAAY,EAAE,CAAC;GAChD,KAAK,IAAI,IAAI;GACb,KAAK,IAAI,IAAI;GACb,OAAO,IAAI,IAAI,IAAI,IAAI,IAAI;GAC3B,MAAM,OAAO,WAAW,KAAK,IAAI,EAAE,YAAY,EAAE,CAAC;GAClD,QAAQ,OAAO,IAAI;GACnB,MAAM;GACN,UAAU,OAAO,WAAW,SAAS,IAAI,EAAE,YAAY,CAAC,CAAC;GACzD,SAAS,OAAO,WAAW,kBAAkB,IAAI,EAAE,YAAY,CAAC,CAAC;GACjE,IAAI,SAAS,QAAQ,GAAI;GACzB,IAAI,SAAS,QAAQ,EAAG;GACxB,IAAI,SAAS,QAAQ,GAAI;GACzB,KAAK,mBAAmB,IAAI;GAC5B,KAAK,SAAS,QAAQ,EAAG;GACzB,KAAK,SAAS,QAAQ,EAAG;GACzB,KAAK,SAAS,QAAQ,GAAI;GAC1B,KAAK,SAAS,QAAQ,GAAI;EAC5B,GACA,MACA,CACF;CACF;AACF,CAAC;;;;;;;;AASD,IAAa,qBAAqB,IAAI,KAAK;CACzC,MAAM;CACN,aACE;CACF,aAAa,UAAU,OAAO;EAC5B,GAAG,UAAU,OAAO,EAAE,SAAS,EAAE,YAAY,wCAAwC;EACrF,GAAG,UACA,OAAO,EACP,SAAS,EACT,YAAY,2DAA2D;CAC5E,CAAC;CACD,SAAS,OAAO,SAAS;EACvB,MAAM,EAAE,GAAG,MAAM,GAAG,SAAS;EAC7B,MAAM,IAAI,aAAa,IAAI;EAC3B,IAAI,WAAW,GAAG,OAAO,eAAe,EAAE;EAC1C,MAAM,IAAI,aAAa,IAAI;EAC3B,IAAI,WAAW,GAAG,OAAO,eAAe,EAAE;EAE1C,IAAI,EAAE,WAAW,EAAE,QACjB,OAAO,6CAA6C,EAAE,OAAO,OAAO,EAAE,OAAO;EAC/E,IAAI,EAAE,SAAS,GAAG,OAAO;EAEzB,IAAI;GACF,MAAM,IAAI,kBAAkB,GAAG,CAAC;GAChC,MAAM,OAAO,KAAK,IAAI,CAAC;GACvB,MAAM,YAAY,IAAI,IAAI,aAAa,IAAI,IAAI,aAAa;GAC5D,MAAM,WACJ,QAAQ,KACJ,gBACA,QAAQ,KACN,WACA,QAAQ,KACN,aACA,QAAQ,KACN,SACA;GACZ,OAAO,OAAO,EAAE,QAAQ,CAAC,EAAE,UAAU,IAAI,IAAI,KAAK,QAAQ,CAAC,EAAE,0CAA0C,SAAS,GAAG,UAAU;EAC/H,SAAS,KAAK;GACZ,OAAO,UAAU,QAAQ,GAAG,IAAI,IAAI,UAAU,OAAO,GAAG;EAC1D;CACF;AACF,CAAC;;;;;;;;;;AAWD,IAAa,qBAAqB,IAAI,KAAK;CACzC,MAAM;CACN,aACE;CACF,aAAa,UAAU,OAAO;EAC5B,SAAS,UAAU,OAAO,EAAE,SAAS,EAAE,YAAY,uBAAuB;EAC1E,WAAW,UACR,OAAO,EACP,MACC,qBACA,qBACA,4BACA,iBACA,eACA,cACA,QACA,gBACA,iBACF,EACC,SAAS,EACT,YAAY,yBAAyB;EACxC,QAAQ,UAAU,OAAO,EAAE,QAAQ,CAAC,EAAE,YAAY,2CAA2C;EAC7F,WAAW,UACR,OAAO,EACP,QAAQ,CAAG,EACX,YAAY,uDAAuD;CACxE,CAAC;CACD,SAAS,OAAO,SAAS;EACvB,MAAM,EAAE,SAAS,WAAW,QAAQ,cAAc;EAMlD,MAAM,OAAO,aAAa,OAAO;EACjC,IAAI,WAAW,MAAM,OAAO,UAAU,KAAK;EAE3C,QAAQ,WAAR;GACE,KAAK,qBAAqB;IACxB,MAAM,KAAK,IAAI,IAAI;IACnB,MAAM,KAAK,IAAI,IAAI;IACnB,IAAI,OAAO,IAAI,OAAO,KAAK,UAAU,KAAK,UAAU,CAAC,CAAC;IACtD,OAAO,KAAK,UAAU,KAAK,KAAK,MAAM,OAAO,aAAa,IAAI,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC;GAC7F;GAEA,KAAK,qBAAqB;IACxB,MAAM,IAAI,KAAK,IAAI;IACnB,MAAM,KAAK,kBAAkB,IAAI;IACjC,IAAI,OAAO,GAAG,OAAO,KAAK,UAAU,KAAK,UAAU,CAAC,CAAC;IACrD,OAAO,KAAK,UAAU,KAAK,KAAK,MAAM,OAAO,WAAW,OAAO,GAAG,GAAG,EAAE,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC;GACvF;GAEA,KAAK,4BAA4B;IAC/B,MAAM,QAAQ,IAAI,IAAI;IACtB,IAAI,UAAU,GAAG,OAAO,KAAK,UAAU,KAAK,UAAU,CAAC,CAAC;IACxD,OAAO,KAAK,UAAU,KAAK,KAAK,MAAM,OAAO,YAAa,IAAI,QAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC;GAC1F;GAEA,KAAK,iBAAiB;IACpB,MAAM,SAAmB,CAAC;IAC1B,IAAI,MAAM;IACV,KAAK,MAAM,KAAK,MAAM;KACpB,OAAO;KACP,OAAO,KAAK,OAAO,WAAW,IAAI,YAAY,EAAE,CAAC,CAAC;IACpD;IACA,OAAO,KAAK,UAAU,MAAM;GAC9B;GAEA,KAAK,eAAe;IAClB,MAAM,IAAI,KAAK,IAAI,GAAG,KAAK,MAAM,MAAM,CAAC;IACxC,OAAO,KAAK,UACV,KAAK,KAAK,GAAG,MAAM;KACjB,MAAM,QAAQ,KAAK,MAAM,KAAK,IAAI,GAAG,IAAI,IAAI,CAAC,GAAG,IAAI,CAAC;KACtD,OAAO,OAAO,WAAW,KAAK,KAAK,EAAE,YAAY,CAAC,CAAC;IACrD,CAAC,CACH;GACF;GAEA,KAAK,cAAc;IACjB,MAAM,UAA6B,CAAC,IAAI;IACxC,KAAK,IAAI,IAAI,GAAG,IAAI,KAAK,QAAQ,KAC/B,IAAI,KAAK,IAAI,OAAO,GAClB,QAAQ,KAAK,IAAI;SAEjB,QAAQ,KACN,OAAO,aACF,KAAK,KAAK,KAAK,IAAI,MAAM,KAAK,IAAI,KAAK,IAAI,EAAE,IAAK,KAAK,QAAQ,CAAC,CACrE,CACF;IAGJ,OAAO,KAAK,UAAU,OAAO;GAC/B;GAEA,KAAK,QAAQ;IACX,MAAM,SAAS,CAAC,GAAG,IAAI,EAAE,MAAM,GAAG,MAAM,IAAI,CAAC;IAC7C,OAAO,KAAK,UAAU,KAAK,KAAK,MAAM,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAC;GAC9D;GAEA,KAAK,gBAAgB;IACnB,MAAM,SAAS,CAAC,GAAG,IAAI,EAAE,MAAM,GAAG,MAAM,IAAI,CAAC;IAC7C,MAAM,KAAK,SAAS,QAAQ,GAAI;IAChC,MAAM,KAAK,SAAS,QAAQ,GAAI;IAChC,MAAM,MAAM,KAAK;IACjB,MAAM,KAAK,KAAK,MAAM;IACtB,MAAM,KAAK,KAAK,MAAM;IACtB,MAAM,WAAW,KACd,KAAK,GAAG,OAAO;KAAE,OAAO;KAAG,OAAO;IAAE,EAAE,EACtC,QAAQ,EAAE,YAAY,QAAQ,MAAM,QAAQ,EAAE;IACjD,IAAI,SAAS,WAAW,GAAG,OAAO;IAClC,OAAO,GAAG,SAAS,OAAO,yBAAyB,SAAS,KAAK,MAAM,MAAM,EAAE,MAAM,MAAM,EAAE,OAAO,EAAE,KAAK,IAAI;GACjH;GAEA,KAAK,mBAAmB;IACtB,MAAM,IAAI,KAAK,IAAI;IACnB,MAAM,KAAK,kBAAkB,IAAI;IACjC,MAAM,WAAW,KACd,KAAK,GAAG,OAAO;KAAE,OAAO;KAAG,OAAO;KAAG,GAAG,OAAO,IAAI,IAAI,KAAK,IAAI,OAAO,GAAG,GAAG,EAAE,CAAC;IAAE,EAAE,EACpF,QAAQ,MAAM,EAAE,IAAI,SAAS;IAChC,IAAI,SAAS,WAAW,GAAG,OAAO,+BAA+B,UAAU;IAC3E,OAAO,GAAG,SAAS,OAAO,8BAA8B,UAAU,MAAM,SAAS,KAAK,MAAM,MAAM,EAAE,MAAM,MAAM,EAAE,MAAM,QAAQ,EAAE,EAAE,QAAQ,CAAC,EAAE,EAAE,EAAE,KAAK,IAAI;GAC9J;GAEA,SACE,OAAO,6BAA6B,UAAU;EAClD;CACF;AACF,CAAC;;;;;;;;;AAUD,IAAa,qBAAqB,IAAI,KAAK;CACzC,MAAM;CACN,aAAa;CACb,aAAa,UAAU,OAAO;EAC5B,SAAS,UAAU,OAAO,EAAE,SAAS,EAAE,YAAY,uBAAuB;EAC1E,MAAM,UAAU,OAAO,EAAE,QAAQ,EAAE,EAAE,YAAY,wCAAwC;CAC3F,CAAC;CACD,SAAS,OAAO,SAAS;EACvB,MAAM,EAAE,SAAS,SAAS;EAC1B,MAAM,OAAO,aAAa,OAAO;EACjC,IAAI,WAAW,MAAM,OAAO,UAAU,KAAK;EAE3C,MAAM,WAAW,KAAK,IAAI,GAAG,KAAK,IAAI,KAAK,KAAK,MAAM,IAAI,CAAC,CAAC;EAE5D,IAAI;GACF,MAAM,SAAS,oBAAoB,MAAM,QAAQ;GACjD,MAAM,OAAiB,CAAC;GACxB,MAAM,kBAAkB;IACtB,IAAI,IAAI;IACR,KAAK,IAAI,IAAI,GAAG,IAAI,OAAO,SAAS,GAAG,KAAK;KAC1C,MAAM,SAAS,MAAM,OAAO,SAAS;KACrC,MAAM,QAAQ,KAAK,QAAQ,MACzB,SAAS,KAAK,OAAO,MAAM,KAAK,OAAO,IAAI,KAAK,KAAK,OAAO,MAAM,IAAI,OAAO,IAAI,EACnF,EAAE;KACF,IAAI,QAAQ,GAAG,IAAI;IACrB;IACA,OAAO;GACT,GAAG;GAEH,KAAK,IAAI,IAAI,GAAG,IAAI,OAAO,SAAS,GAAG,KAAK;IAC1C,MAAM,SAAS,MAAM,OAAO,SAAS;IACrC,MAAM,QAAQ,KAAK,QAAQ,MACzB,SAAS,KAAK,OAAO,MAAM,KAAK,OAAO,IAAI,KAAK,KAAK,OAAO,MAAM,IAAI,OAAO,IAAI,EACnF,EAAE;IACF,MAAM,OAAQ,QAAQ,KAAK,SAAU,KAAK,QAAQ,CAAC;IACnD,MAAM,MAAM,IAAI,OAAO,WAAW,IAAI,KAAK,MAAO,QAAQ,WAAY,EAAE,IAAI,CAAC;IAC7E,MAAM,QAAQ,IAAI,OAAO,GAAG,YAAY,CAAC,EAAE,IAAI,OAAO,IAAI,GAAG,YAAY,CAAC,IAAI,SAAS,MAAM;IAC7F,KAAK,KAAK,GAAG,MAAM,OAAO,EAAE,EAAE,GAAG,OAAO,KAAK,EAAE,SAAS,CAAC,EAAE,IAAI,IAAI,SAAS,CAAC,EAAE,KAAK,KAAK;GAC3F;GAEA,OAAO,KAAK,KAAK,IAAI;EACvB,SAAS,KAAK;GACZ,OAAO,UAAU,QAAQ,GAAG,IAAI,IAAI,UAAU,OAAO,GAAG;EAC1D;CACF;AACF,CAAC"}

package/batteries/tools/string_processing/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Pre-constructed tools for casing, trimming, normalizing, and transforming strings.
+ *
+ * @module @nhtio/adk/batteries/tools/string_processing
+ *
+ * @remarks
+ * Pre-constructed bundled tools for the `string_processing` category. Import individually, the whole
+ * category, or import every tool via `@nhtio/adk/batteries`.
+ */
+import { Tool } from "../../../common";
+/**
+ * Apply an ordered pipeline of string transformations.
+ *
+ * @remarks
+ * Each operation reads the previous step's output. Most operations return strings; `count_*`
+ * return numbers and `split` returns an array — once a non-string flows through, subsequent
+ * operations report an error rather than coercing. The result is always serialised to a string
+ * (arrays become JSON; numbers/booleans are stringified).
+ */
+export declare const stringTransformTool: Tool<import("../../../common").SpooledArtifact>;
+/**
+ * Extract all matches of a regular expression from a string.
+ *
+ * @remarks
+ * The `g` flag is always enabled. `group` selects which capture group to return per match (0 =
+ * full match). Output is at most 500 matches; if truncated, the suffix `(truncated at 500)` is
+ * appended.
+ */
+export declare const stringExtractTool: Tool<import("../../../common").SpooledArtifact>;