@nhtio/adk 1.20260607.2 → 1.20260609.1

package/batteries/tools/structured_data.mjs

@@ -1,6 +1,6 @@
-import { o as isError } from "../../tool_registry-D1pSSlsd.mjs";
-import { t as Tool } from "../../tool-CMhaDRNd.mjs";
-import "../../common-BT0nfCi9.mjs";
+import { c as isObject, o as isError } from "../../tool_registry-791Vrjtf.mjs";
+import { t as Tool } from "../../tool-wMYMVl60.mjs";
+import "../../common-DYDUi99O.mjs";
 import "../../guards.mjs";
 import { validator } from "@nhtio/validation";
 //#region src/batteries/tools/structured_data/index.ts
@@ -49,29 +49,24 @@ var formatTableTool = new Tool({
 		}
 		if (!Array.isArray(rows)) return "Error: Input must be a JSON array.";
 		if (rows.length === 0) return "Empty array — no data to display.";
+		if (!explicitColumns && !isObject(rows[0])) return "Error: Cannot infer columns — the first row is not an object. Provide \"columns\", or pass an array of objects.";
 		const columns = explicitColumns ?? Object.keys(rows[0]);
+		const cell = (row, col) => isObject(row) ? row[col] : void 0;
 		if (format === "csv") {
 			const lines = [columns.map(csvEscape).join(",")];
-			for (const row of rows) {
-				const obj = row;
-				lines.push(columns.map((col) => csvEscape(obj[col])).join(","));
-			}
+			for (const row of rows) lines.push(columns.map((col) => csvEscape(cell(row, col))).join(","));
 			return lines.join("\n");
 		}
 		if (format === "tsv") {
 			const lines = [columns.map(tsvEscape).join("	")];
-			for (const row of rows) {
-				const obj = row;
-				lines.push(columns.map((col) => tsvEscape(obj[col])).join("	"));
-			}
+			for (const row of rows) lines.push(columns.map((col) => tsvEscape(cell(row, col))).join("	"));
 			return lines.join("\n");
 		}
 		return [
 			"| " + columns.map(mdEscape).join(" | ") + " |",
 			"| " + columns.map(() => "---").join(" | ") + " |",
 			...rows.map((row) => {
-				const obj = row;
-				return "| " + columns.map((col) => mdEscape(obj[col])).join(" | ") + " |";
+				return "| " + columns.map((col) => mdEscape(cell(row, col))).join(" | ") + " |";
 			})
 		].join("\n");
 	}

package/batteries/tools/structured_data.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"structured_data.mjs","names":[],"sources":["../../../src/batteries/tools/structured_data/index.ts"],"sourcesContent":["/**\n * Pre-constructed tools for transforming arrays and objects into tables and tabular text.\n *\n * @module @nhtio/adk/batteries/tools/structured_data\n *\n * @remarks\n * Pre-constructed bundled tools for the `structured_data` category. Import individually, the whole\n * category, or import every tool via `@nhtio/adk/batteries`.\n */\n\nimport { Tool } from '@nhtio/adk/common'\nimport { isError } from '@nhtio/adk/guards'\nimport { validator } from '@nhtio/validation'\n\nfunction csvEscape(value: unknown): string {\n  const str = value === null || value === undefined ? '' : String(value)\n  if (str.includes(',') || str.includes('\"') || str.includes('\\n') || str.includes('\\r')) {\n    return '\"' + str.replace(/\"/g, '\"\"') + '\"'\n  }\n  return str\n}\n\nfunction tsvEscape(value: unknown): string {\n  const str = value === null || value === undefined ? '' : String(value)\n  return str.replace(/\\t/g, ' ').replace(/\\r?\\n/g, ' ')\n}\n\nfunction mdEscape(value: unknown): string {\n  return String(value === null || value === undefined ? '' : value)\n    .replace(/\\|/g, '\\\\|')\n    .replace(/\\r?\\n/g, ' ')\n}\n\n/**\n * Convert a JSON array of objects into a formatted table.\n *\n * @remarks\n * Supports `markdown`, `csv`, and `tsv` output. Columns default to the keys of the first row;\n * supply `columns` to control which keys appear and in what order.\n */\nexport const formatTableTool = new Tool({\n  name: 'format_table',\n  description:\n    'Convert a JSON array of objects into a formatted table. Supports Markdown, CSV, and TSV output.',\n  inputSchema: validator.object({\n    data: validator.string().required().description('JSON array of objects as a string'),\n    format: validator\n      .string()\n      .valid('markdown', 'csv', 'tsv')\n      .required()\n      .description('Output format'),\n    columns: validator\n      .array()\n      .items(validator.string())\n      .optional()\n      .description(\n        'Column keys to include, in order. If omitted, all keys from the first row are used.'\n      ),\n  }),\n  handler: async (args) => {\n    const {\n      data,\n      format,\n      columns: explicitColumns,\n    } = args as {\n      data: string\n      format: 'markdown' | 'csv' | 'tsv'\n      columns?: string[]\n    }\n\n    let rows: unknown[]\n    try {\n      rows = JSON.parse(data)\n    } catch {\n      return 'Error: Invalid JSON input.'\n    }\n\n    if (!Array.isArray(rows)) return 'Error: Input must be a JSON array.'\n    if (rows.length === 0) return 'Empty array — no data to display.'\n\n    const columns = explicitColumns ?? Object.keys(rows[0] as Record<string, unknown>)\n\n    if (format === 'csv') {\n      const lines = [columns.map(csvEscape).join(',')]\n      for (const row of rows) {\n        const obj = row as Record<string, unknown>\n        lines.push(columns.map((col) => csvEscape(obj[col])).join(','))\n      }\n      return lines.join('\\n')\n    }\n\n    if (format === 'tsv') {\n      const lines = [columns.map(tsvEscape).join('\\t')]\n      for (const row of rows) {\n        const obj = row as Record<string, unknown>\n        lines.push(columns.map((col) => tsvEscape(obj[col])).join('\\t'))\n      }\n      return lines.join('\\n')\n    }\n\n    const header = '| ' + columns.map(mdEscape).join(' | ') + ' |'\n    const separator = '| ' + columns.map(() => '---').join(' | ') + ' |'\n    const dataRows = rows.map((row) => {\n      const obj = row as Record<string, unknown>\n      return '| ' + columns.map((col) => mdEscape(obj[col])).join(' | ') + ' |'\n    })\n    return [header, separator, ...dataRows].join('\\n')\n  },\n})\n\n/**\n * Pretty-print or minify a JSON string.\n *\n * @remarks\n * Validates the input as JSON, then re-serialises it with the requested indentation. `indent` is\n * clamped to the range [0, 8]; `0` produces minified output.\n */\nexport const jsonFormatTool = new Tool({\n  name: 'json_format',\n  description: 'Pretty-print or minify a JSON string. Validates JSON and normalises whitespace.',\n  inputSchema: validator.object({\n    data: validator.string().required().description('JSON string to format'),\n    indent: validator\n      .number()\n      .default(2)\n      .description('Indentation spaces (0 = minify, default: 2). Max: 8.'),\n  }),\n  handler: async (args) => {\n    const { data, indent } = args as { data: string; indent: number }\n    try {\n      const parsed = JSON.parse(data)\n      return JSON.stringify(parsed, null, Math.max(0, Math.min(8, Math.floor(indent))))\n    } catch (err) {\n      return `Error: Invalid JSON — ${isError(err) ? err.message : String(err)}`\n    }\n  },\n})\n\nconst FORMAT_PATTERNS: Record<string, { pattern: RegExp; label: string }> = {\n  email: {\n    pattern: /^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$/,\n    label: 'email address',\n  },\n  uuid: {\n    pattern: /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i,\n    label: 'UUID (v1–v5)',\n  },\n  ipv4: {\n    pattern: /^((25[0-5]|2[0-4]\\d|[01]?\\d\\d?)\\.){3}(25[0-5]|2[0-4]\\d|[01]?\\d\\d?)$/,\n    label: 'IPv4 address',\n  },\n  iso_date: {\n    pattern: /^\\d{4}-\\d{2}-\\d{2}$/,\n    label: 'ISO 8601 date (YYYY-MM-DD)',\n  },\n  iso_datetime: {\n    pattern: /^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}(:\\d{2}(\\.\\d+)?)?(Z|[+-]\\d{2}:\\d{2})?$/,\n    label: 'ISO 8601 datetime',\n  },\n  hex_color: {\n    pattern: /^#([0-9a-fA-F]{3}|[0-9a-fA-F]{4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/,\n    label: 'CSS hex color',\n  },\n  phone_e164: {\n    pattern: /^\\+[1-9]\\d{1,14}$/,\n    label: 'E.164 phone number',\n  },\n  semver: {\n    pattern: /^\\d+\\.\\d+\\.\\d+(-[0-9A-Za-z-.]+)?(\\+[0-9A-Za-z-.]+)?$/,\n    label: 'Semantic Version (SemVer)',\n  },\n  integer: {\n    pattern: /^-?\\d+$/,\n    label: 'integer',\n  },\n  decimal: {\n    pattern: /^-?\\d+(\\.\\d+)?$/,\n    label: 'decimal number',\n  },\n  alphanumeric: {\n    pattern: /^[a-zA-Z0-9]+$/,\n    label: 'alphanumeric string',\n  },\n  slug: {\n    pattern: /^[a-z0-9]+(-[a-z0-9]+)*$/,\n    label: 'URL slug',\n  },\n  hex: {\n    pattern: /^(0x)?[0-9a-fA-F]+$/,\n    label: 'hexadecimal string',\n  },\n  base64: {\n    pattern: /^[A-Za-z0-9+/]*={0,2}$/,\n    label: 'base64-encoded string',\n  },\n}\n\n/**\n * Check whether a string matches a known format.\n *\n * @remarks\n * Supported formats: `email`, `uuid` (v1–v5), `ipv4`, `iso_date`, `iso_datetime`, `hex_color`,\n * `phone_e164`, `semver`, `integer`, `decimal`, `alphanumeric`, `slug`, `hex`, `base64`.\n */\nexport const validateFormatTool = new Tool({\n  name: 'validate_format',\n  description:\n    'Check whether a string matches a known format (email, UUID, ISO date, hex colour, phone number, semver, slug, etc.).',\n  inputSchema: validator.object({\n    value: validator.string().required().description('The string to validate'),\n    format: validator\n      .string()\n      .valid(...Object.keys(FORMAT_PATTERNS))\n      .required()\n      .description(\n        `Format to validate against. One of: ${Object.keys(FORMAT_PATTERNS).join(', ')}`\n      ),\n  }),\n  handler: async (args) => {\n    const { value, format } = args as { value: string; format: string }\n    const def = FORMAT_PATTERNS[format]\n    if (!def) {\n      return `Error: Unknown format \"${format}\". Supported: ${Object.keys(FORMAT_PATTERNS).join(', ')}`\n    }\n    const valid = def.pattern.test(value)\n    return valid\n      ? `Valid: \"${value}\" is a valid ${def.label}.`\n      : `Invalid: \"${value}\" is not a valid ${def.label}.`\n  },\n})\n"],"mappings":"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"}
+{"version":3,"file":"structured_data.mjs","names":[],"sources":["../../../src/batteries/tools/structured_data/index.ts"],"sourcesContent":["/**\n * Pre-constructed tools for transforming arrays and objects into tables and tabular text.\n *\n * @module @nhtio/adk/batteries/tools/structured_data\n *\n * @remarks\n * Pre-constructed bundled tools for the `structured_data` category. Import individually, the whole\n * category, or import every tool via `@nhtio/adk/batteries`.\n */\n\nimport { Tool } from '@nhtio/adk/common'\nimport { validator } from '@nhtio/validation'\nimport { isError, isObject } from '@nhtio/adk/guards'\n\nfunction csvEscape(value: unknown): string {\n  const str = value === null || value === undefined ? '' : String(value)\n  if (str.includes(',') || str.includes('\"') || str.includes('\\n') || str.includes('\\r')) {\n    return '\"' + str.replace(/\"/g, '\"\"') + '\"'\n  }\n  return str\n}\n\nfunction tsvEscape(value: unknown): string {\n  const str = value === null || value === undefined ? '' : String(value)\n  return str.replace(/\\t/g, ' ').replace(/\\r?\\n/g, ' ')\n}\n\nfunction mdEscape(value: unknown): string {\n  return String(value === null || value === undefined ? '' : value)\n    .replace(/\\|/g, '\\\\|')\n    .replace(/\\r?\\n/g, ' ')\n}\n\n/**\n * Convert a JSON array of objects into a formatted table.\n *\n * @remarks\n * Supports `markdown`, `csv`, and `tsv` output. Columns default to the keys of the first row;\n * supply `columns` to control which keys appear and in what order.\n */\nexport const formatTableTool = new Tool({\n  name: 'format_table',\n  description:\n    'Convert a JSON array of objects into a formatted table. Supports Markdown, CSV, and TSV output.',\n  inputSchema: validator.object({\n    data: validator.string().required().description('JSON array of objects as a string'),\n    format: validator\n      .string()\n      .valid('markdown', 'csv', 'tsv')\n      .required()\n      .description('Output format'),\n    columns: validator\n      .array()\n      .items(validator.string())\n      .optional()\n      .description(\n        'Column keys to include, in order. If omitted, all keys from the first row are used.'\n      ),\n  }),\n  handler: async (args) => {\n    const {\n      data,\n      format,\n      columns: explicitColumns,\n    } = args as {\n      data: string\n      format: 'markdown' | 'csv' | 'tsv'\n      columns?: string[]\n    }\n\n    let rows: unknown[]\n    try {\n      rows = JSON.parse(data)\n    } catch {\n      return 'Error: Invalid JSON input.'\n    }\n\n    if (!Array.isArray(rows)) return 'Error: Input must be a JSON array.'\n    if (rows.length === 0) return 'Empty array — no data to display.'\n\n    // Columns default to the first row's keys, but only an object row has keys. If columns aren't\n    // given and the first row isn't an object, there's nothing to tabulate — error clearly rather\n    // than throwing on `Object.keys(null)`.\n    if (!explicitColumns && !isObject(rows[0])) {\n      return 'Error: Cannot infer columns — the first row is not an object. Provide \"columns\", or pass an array of objects.'\n    }\n    const columns = explicitColumns ?? Object.keys(rows[0] as Record<string, unknown>)\n\n    // Read a cell safely: a null/primitive row has no properties, so it yields empty cells rather\n    // than throwing on `row[col]`.\n    const cell = (row: unknown, col: string): unknown =>\n      isObject(row) ? (row as Record<string, unknown>)[col] : undefined\n\n    if (format === 'csv') {\n      const lines = [columns.map(csvEscape).join(',')]\n      for (const row of rows) {\n        lines.push(columns.map((col) => csvEscape(cell(row, col))).join(','))\n      }\n      return lines.join('\\n')\n    }\n\n    if (format === 'tsv') {\n      const lines = [columns.map(tsvEscape).join('\\t')]\n      for (const row of rows) {\n        lines.push(columns.map((col) => tsvEscape(cell(row, col))).join('\\t'))\n      }\n      return lines.join('\\n')\n    }\n\n    const header = '| ' + columns.map(mdEscape).join(' | ') + ' |'\n    const separator = '| ' + columns.map(() => '---').join(' | ') + ' |'\n    const dataRows = rows.map((row) => {\n      return '| ' + columns.map((col) => mdEscape(cell(row, col))).join(' | ') + ' |'\n    })\n    return [header, separator, ...dataRows].join('\\n')\n  },\n})\n\n/**\n * Pretty-print or minify a JSON string.\n *\n * @remarks\n * Validates the input as JSON, then re-serialises it with the requested indentation. `indent` is\n * clamped to the range [0, 8]; `0` produces minified output.\n */\nexport const jsonFormatTool = new Tool({\n  name: 'json_format',\n  description: 'Pretty-print or minify a JSON string. Validates JSON and normalises whitespace.',\n  inputSchema: validator.object({\n    data: validator.string().required().description('JSON string to format'),\n    indent: validator\n      .number()\n      .default(2)\n      .description('Indentation spaces (0 = minify, default: 2). Max: 8.'),\n  }),\n  handler: async (args) => {\n    const { data, indent } = args as { data: string; indent: number }\n    try {\n      const parsed = JSON.parse(data)\n      return JSON.stringify(parsed, null, Math.max(0, Math.min(8, Math.floor(indent))))\n    } catch (err) {\n      return `Error: Invalid JSON — ${isError(err) ? err.message : String(err)}`\n    }\n  },\n})\n\nconst FORMAT_PATTERNS: Record<string, { pattern: RegExp; label: string }> = {\n  email: {\n    pattern: /^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$/,\n    label: 'email address',\n  },\n  uuid: {\n    pattern: /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i,\n    label: 'UUID (v1–v5)',\n  },\n  ipv4: {\n    pattern: /^((25[0-5]|2[0-4]\\d|[01]?\\d\\d?)\\.){3}(25[0-5]|2[0-4]\\d|[01]?\\d\\d?)$/,\n    label: 'IPv4 address',\n  },\n  iso_date: {\n    pattern: /^\\d{4}-\\d{2}-\\d{2}$/,\n    label: 'ISO 8601 date (YYYY-MM-DD)',\n  },\n  iso_datetime: {\n    pattern: /^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}(:\\d{2}(\\.\\d+)?)?(Z|[+-]\\d{2}:\\d{2})?$/,\n    label: 'ISO 8601 datetime',\n  },\n  hex_color: {\n    pattern: /^#([0-9a-fA-F]{3}|[0-9a-fA-F]{4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/,\n    label: 'CSS hex color',\n  },\n  phone_e164: {\n    pattern: /^\\+[1-9]\\d{1,14}$/,\n    label: 'E.164 phone number',\n  },\n  semver: {\n    pattern: /^\\d+\\.\\d+\\.\\d+(-[0-9A-Za-z-.]+)?(\\+[0-9A-Za-z-.]+)?$/,\n    label: 'Semantic Version (SemVer)',\n  },\n  integer: {\n    pattern: /^-?\\d+$/,\n    label: 'integer',\n  },\n  decimal: {\n    pattern: /^-?\\d+(\\.\\d+)?$/,\n    label: 'decimal number',\n  },\n  alphanumeric: {\n    pattern: /^[a-zA-Z0-9]+$/,\n    label: 'alphanumeric string',\n  },\n  slug: {\n    pattern: /^[a-z0-9]+(-[a-z0-9]+)*$/,\n    label: 'URL slug',\n  },\n  hex: {\n    pattern: /^(0x)?[0-9a-fA-F]+$/,\n    label: 'hexadecimal string',\n  },\n  base64: {\n    pattern: /^[A-Za-z0-9+/]*={0,2}$/,\n    label: 'base64-encoded string',\n  },\n}\n\n/**\n * Check whether a string matches a known format.\n *\n * @remarks\n * Supported formats: `email`, `uuid` (v1–v5), `ipv4`, `iso_date`, `iso_datetime`, `hex_color`,\n * `phone_e164`, `semver`, `integer`, `decimal`, `alphanumeric`, `slug`, `hex`, `base64`.\n */\nexport const validateFormatTool = new Tool({\n  name: 'validate_format',\n  description:\n    'Check whether a string matches a known format (email, UUID, ISO date, hex colour, phone number, semver, slug, etc.).',\n  inputSchema: validator.object({\n    value: validator.string().required().description('The string to validate'),\n    format: validator\n      .string()\n      .valid(...Object.keys(FORMAT_PATTERNS))\n      .required()\n      .description(\n        `Format to validate against. One of: ${Object.keys(FORMAT_PATTERNS).join(', ')}`\n      ),\n  }),\n  handler: async (args) => {\n    const { value, format } = args as { value: string; format: string }\n    const def = FORMAT_PATTERNS[format]\n    if (!def) {\n      return `Error: Unknown format \"${format}\". Supported: ${Object.keys(FORMAT_PATTERNS).join(', ')}`\n    }\n    const valid = def.pattern.test(value)\n    return valid\n      ? `Valid: \"${value}\" is a valid ${def.label}.`\n      : `Invalid: \"${value}\" is not a valid ${def.label}.`\n  },\n})\n"],"mappings":"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"}

package/batteries/tools/text_analysis.cjs

@@ -1,8 +1,8 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 require("../../chunk-Ble4zEEl.js");
-const require_tool = require("../../tool-CVyZkFC7.js");
-require("../../common-Cj8TaQ9U.js");
-const require_spooled_markdown_artifact = require("../../spooled_markdown_artifact-CALSDxIx.js");
+const require_tool = require("../../tool-D5WGVIcI.js");
+require("../../common-DZl3ADJs.js");
+const require_spooled_markdown_artifact = require("../../spooled_markdown_artifact-ClX72lek.js");
 let _nhtio_validation = require("@nhtio/validation");
 //#region src/batteries/tools/text_analysis/index.ts
 /**

package/batteries/tools/text_analysis.mjs

@@ -1,6 +1,6 @@
-import { t as Tool } from "../../tool-CMhaDRNd.mjs";
-import "../../common-BT0nfCi9.mjs";
-import { n as SpooledJsonArtifact } from "../../spooled_markdown_artifact-Ci5UL7l4.mjs";
+import { t as Tool } from "../../tool-wMYMVl60.mjs";
+import "../../common-DYDUi99O.mjs";
+import { n as SpooledJsonArtifact } from "../../spooled_markdown_artifact-wkrBF3oX.mjs";
 import { validator } from "@nhtio/validation";
 //#region src/batteries/tools/text_analysis/index.ts
 /**

package/batteries/tools/text_comparison.cjs

@@ -1,7 +1,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 require("../../chunk-Ble4zEEl.js");
-const require_tool = require("../../tool-CVyZkFC7.js");
-require("../../common-Cj8TaQ9U.js");
+const require_tool = require("../../tool-D5WGVIcI.js");
+require("../../common-DZl3ADJs.js");
 let _nhtio_validation = require("@nhtio/validation");
 let diff = require("diff");
 let fastest_levenshtein = require("fastest-levenshtein");

package/batteries/tools/text_comparison.mjs

@@ -1,5 +1,5 @@
-import { t as Tool } from "../../tool-CMhaDRNd.mjs";
-import "../../common-BT0nfCi9.mjs";
+import { t as Tool } from "../../tool-wMYMVl60.mjs";
+import "../../common-DYDUi99O.mjs";
 import { validator } from "@nhtio/validation";
 import { diffLines, diffWords } from "diff";
 import { distance } from "fastest-levenshtein";

package/batteries/tools/time.cjs

@@ -1,7 +1,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 require("../../chunk-Ble4zEEl.js");
-const require_tool = require("../../tool-CVyZkFC7.js");
-require("../../common-Cj8TaQ9U.js");
+const require_tool = require("../../tool-D5WGVIcI.js");
+require("../../common-DZl3ADJs.js");
 let _nhtio_validation = require("@nhtio/validation");
 let luxon = require("luxon");
 //#region src/batteries/tools/time/index.ts

package/batteries/tools/time.mjs

@@ -1,5 +1,5 @@
-import { t as Tool } from "../../tool-CMhaDRNd.mjs";
-import "../../common-BT0nfCi9.mjs";
+import { t as Tool } from "../../tool-wMYMVl60.mjs";
+import "../../common-DYDUi99O.mjs";
 import { validator } from "@nhtio/validation";
 import { DateTime, IANAZone } from "luxon";
 //#region src/batteries/tools/time/index.ts

package/batteries/tools/unit_conversion.cjs

@@ -1,7 +1,8 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 require("../../chunk-Ble4zEEl.js");
-const require_tool = require("../../tool-CVyZkFC7.js");
-require("../../common-Cj8TaQ9U.js");
+const require_tool = require("../../tool-D5WGVIcI.js");
+require("../../common-DZl3ADJs.js");
+const require_lib_helpers_bignum = require("../../lib/helpers/bignum.cjs");
 let _nhtio_validation = require("@nhtio/validation");
 //#region src/batteries/tools/unit_conversion/index.ts
 /**
@@ -425,15 +426,17 @@ var convertUnitTool = new require_tool.Tool({
 	inputSchema: _nhtio_validation.validator.object({
 		value: _nhtio_validation.validator.number().required().description("Numeric value to convert"),
 		from: _nhtio_validation.validator.string().required().description(`Source unit key. Supported keys: ${ALL_UNIT_KEYS}`),
-		to: _nhtio_validation.validator.string().required().description("Target unit key (must be in the same category as source)")
+		to: _nhtio_validation.validator.string().required().description("Target unit key (must be in the same category as source)"),
+		precision: _nhtio_validation.validator.number().default(8).description(`Significant digits in the result (default: 8).`)
 	}),
 	handler: async (args) => {
-		const { value, from, to } = args;
+		const { value, from, to, precision } = args;
 		if (TEMP_UNITS.has(from) || TEMP_UNITS.has(to)) {
 			if (!TEMP_UNITS.has(from)) return `Error: "${from}" is not a temperature unit. Use C, F, or K.`;
 			if (!TEMP_UNITS.has(to)) return `Error: "${to}" is not a temperature unit. Use C, F, or K.`;
-			const result = fromKelvin(toKelvin(value, from), to);
-			const rounded = Number.parseFloat(result.toPrecision(10));
+			const kelvin = toKelvin(value, from);
+			if (kelvin < -1e-9) return `Error: ${value}${TEMP_LABELS[from]} is below absolute zero (0 K); not a physical temperature.`;
+			const rounded = require_lib_helpers_bignum.formatBig(fromKelvin(kelvin, to), precision);
 			return `${value}${TEMP_LABELS[from]} = ${rounded}${TEMP_LABELS[to]}`;
 		}
 		const fromDef = UNITS[from];
@@ -441,8 +444,7 @@ var convertUnitTool = new require_tool.Tool({
 		if (!fromDef) return `Error: Unknown unit "${from}". Supported: ${ALL_UNIT_KEYS}`;
 		if (!toDef) return `Error: Unknown unit "${to}". Supported: ${ALL_UNIT_KEYS}`;
 		if (fromDef.category !== toDef.category) return `Error: Cannot convert "${from}" (${fromDef.category}) to "${to}" (${toDef.category}) — different categories.`;
-		const result = value * fromDef.factor / toDef.factor;
-		const rounded = Number.parseFloat(result.toPrecision(10));
+		const rounded = require_lib_helpers_bignum.formatBig(require_lib_helpers_bignum.bigScale(value, fromDef.factor, toDef.factor), precision);
 		return `${value} ${fromDef.label} = ${rounded} ${toDef.label}`;
 	}
 });

package/batteries/tools/unit_conversion.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"unit_conversion.cjs","names":[],"sources":["../../../src/batteries/tools/unit_conversion/index.ts"],"sourcesContent":["/**\n * Pre-constructed tools for converting values across common measurement units.\n *\n * @module @nhtio/adk/batteries/tools/unit_conversion\n *\n * @remarks\n * Pre-constructed bundled tools for the `unit_conversion` category. Import individually, the whole\n * category, or import every tool via `@nhtio/adk/batteries`.\n */\n\nimport { Tool } from '@nhtio/adk/common'\nimport { validator } from '@nhtio/validation'\n\ntype UnitDef = { category: string; factor: number; label: string }\n\nconst UNITS: Record<string, UnitDef> = {\n  // Length (base: metre)\n  m: { category: 'length', factor: 1, label: 'metres' },\n  km: { category: 'length', factor: 1000, label: 'kilometres' },\n  cm: { category: 'length', factor: 0.01, label: 'centimetres' },\n  mm: { category: 'length', factor: 0.001, label: 'millimetres' },\n  mi: { category: 'length', factor: 1609.344, label: 'miles' },\n  ft: { category: 'length', factor: 0.3048, label: 'feet' },\n  in: { category: 'length', factor: 0.0254, label: 'inches' },\n  yd: { category: 'length', factor: 0.9144, label: 'yards' },\n  nmi: { category: 'length', factor: 1852, label: 'nautical miles' },\n\n  // Mass (base: gram)\n  g: { category: 'mass', factor: 1, label: 'grams' },\n  kg: { category: 'mass', factor: 1000, label: 'kilograms' },\n  mg: { category: 'mass', factor: 0.001, label: 'milligrams' },\n  t: { category: 'mass', factor: 1_000_000, label: 'metric tons' },\n  lb: { category: 'mass', factor: 453.59237, label: 'pounds' },\n  oz: { category: 'mass', factor: 28.349523125, label: 'ounces' },\n  st: { category: 'mass', factor: 6350.29318, label: 'stone' },\n\n  // Volume (base: litre)\n  L: { category: 'volume', factor: 1, label: 'litres' },\n  mL: { category: 'volume', factor: 0.001, label: 'millilitres' },\n  m3: { category: 'volume', factor: 1000, label: 'cubic metres' },\n  cm3: { category: 'volume', factor: 0.001, label: 'cubic centimetres' },\n  gal: { category: 'volume', factor: 3.785411784, label: 'US gallons' },\n  qt: { category: 'volume', factor: 0.946352946, label: 'US quarts' },\n  pt: { category: 'volume', factor: 0.473176473, label: 'US pints' },\n  cup: { category: 'volume', factor: 0.2365882365, label: 'US cups' },\n  floz: { category: 'volume', factor: 0.029573529562, label: 'US fluid ounces' },\n  tbsp: { category: 'volume', factor: 0.014786764781, label: 'tablespoons' },\n  tsp: { category: 'volume', factor: 0.0049289215938, label: 'teaspoons' },\n\n  // Speed (base: m/s)\n  m_s: { category: 'speed', factor: 1, label: 'm/s' },\n  km_h: { category: 'speed', factor: 1 / 3.6, label: 'km/h' },\n  mph: { category: 'speed', factor: 0.44704, label: 'mph' },\n  kn: { category: 'speed', factor: 0.514444, label: 'knots' },\n  ft_s: { category: 'speed', factor: 0.3048, label: 'ft/s' },\n\n  // Area (base: m²)\n  m2: { category: 'area', factor: 1, label: 'm²' },\n  km2: { category: 'area', factor: 1_000_000, label: 'km²' },\n  cm2: { category: 'area', factor: 0.0001, label: 'cm²' },\n  mm2: { category: 'area', factor: 0.000001, label: 'mm²' },\n  ft2: { category: 'area', factor: 0.09290304, label: 'sq ft' },\n  in2: { category: 'area', factor: 0.00064516, label: 'sq in' },\n  yd2: { category: 'area', factor: 0.83612736, label: 'sq yd' },\n  acre: { category: 'area', factor: 4046.8564224, label: 'acres' },\n  ha: { category: 'area', factor: 10_000, label: 'hectares' },\n\n  // Data storage (base: bit)\n  bit: { category: 'data', factor: 1, label: 'bits' },\n  B: { category: 'data', factor: 8, label: 'bytes' },\n  KB: { category: 'data', factor: 8_000, label: 'kilobytes' },\n  MB: { category: 'data', factor: 8_000_000, label: 'megabytes' },\n  GB: { category: 'data', factor: 8_000_000_000, label: 'gigabytes' },\n  TB: { category: 'data', factor: 8_000_000_000_000, label: 'terabytes' },\n  KiB: { category: 'data', factor: 8 * 1024, label: 'kibibytes' },\n  MiB: { category: 'data', factor: 8 * 1024 ** 2, label: 'mebibytes' },\n  GiB: { category: 'data', factor: 8 * 1024 ** 3, label: 'gibibytes' },\n  TiB: { category: 'data', factor: 8 * 1024 ** 4, label: 'tebibytes' },\n\n  // Time (base: second)\n  ms: { category: 'time', factor: 0.001, label: 'milliseconds' },\n  s: { category: 'time', factor: 1, label: 'seconds' },\n  min: { category: 'time', factor: 60, label: 'minutes' },\n  h: { category: 'time', factor: 3600, label: 'hours' },\n  d: { category: 'time', factor: 86400, label: 'days' },\n  wk: { category: 'time', factor: 604800, label: 'weeks' },\n\n  // Energy (base: joule)\n  J: { category: 'energy', factor: 1, label: 'joules' },\n  kJ: { category: 'energy', factor: 1000, label: 'kilojoules' },\n  cal: { category: 'energy', factor: 4.184, label: 'calories' },\n  kcal: { category: 'energy', factor: 4184, label: 'kilocalories' },\n  Wh: { category: 'energy', factor: 3600, label: 'watt-hours' },\n  kWh: { category: 'energy', factor: 3_600_000, label: 'kilowatt-hours' },\n  BTU: { category: 'energy', factor: 1055.05585, label: 'BTU' },\n\n  // Pressure (base: pascal)\n  Pa: { category: 'pressure', factor: 1, label: 'pascals' },\n  kPa: { category: 'pressure', factor: 1000, label: 'kilopascals' },\n  MPa: { category: 'pressure', factor: 1_000_000, label: 'megapascals' },\n  bar: { category: 'pressure', factor: 100_000, label: 'bar' },\n  psi: { category: 'pressure', factor: 6894.757, label: 'psi' },\n  atm: { category: 'pressure', factor: 101325, label: 'atm' },\n  mmHg: { category: 'pressure', factor: 133.322, label: 'mmHg' },\n\n  // Angle (base: radian)\n  rad: { category: 'angle', factor: 1, label: 'radians' },\n  deg: { category: 'angle', factor: Math.PI / 180, label: 'degrees' },\n  grad: { category: 'angle', factor: Math.PI / 200, label: 'gradians' },\n}\n\nconst TEMP_UNITS = new Set(['C', 'F', 'K'])\ntype TempUnit = 'C' | 'F' | 'K'\nconst TEMP_LABELS: Record<TempUnit, string> = { C: '°C', F: '°F', K: 'K' }\n\nfunction toKelvin(value: number, unit: TempUnit): number {\n  if (unit === 'C') return value + 273.15\n  if (unit === 'F') return (value - 32) * (5 / 9) + 273.15\n  return value\n}\n\nfunction fromKelvin(kelvin: number, unit: TempUnit): number {\n  if (unit === 'C') return kelvin - 273.15\n  if (unit === 'F') return (kelvin - 273.15) * (9 / 5) + 32\n  return kelvin\n}\n\nconst ALL_UNIT_KEYS = [...Object.keys(UNITS), 'C', 'F', 'K'].join(', ')\n\n/**\n * Convert a numeric value between units of the same physical category.\n *\n * @remarks\n * Supported categories: length, mass, volume, temperature, speed, area, data, time, energy,\n * pressure, angle. Uses static conversion tables — no external data required. Temperature is\n * handled specially via a Kelvin intermediate to preserve precision across `C`/`F`/`K`.\n */\nexport const convertUnitTool = new Tool({\n  name: 'convert_unit',\n  description:\n    'Convert a numeric value between units of the same category (length, mass, volume, temperature, speed, area, data, time, energy, pressure, angle). Uses static lookup tables — no external data required.',\n  inputSchema: validator.object({\n    value: validator.number().required().description('Numeric value to convert'),\n    from: validator\n      .string()\n      .required()\n      .description(`Source unit key. Supported keys: ${ALL_UNIT_KEYS}`),\n    to: validator\n      .string()\n      .required()\n      .description('Target unit key (must be in the same category as source)'),\n  }),\n  handler: async (args) => {\n    const { value, from, to } = args as { value: number; from: string; to: string }\n\n    if (TEMP_UNITS.has(from) || TEMP_UNITS.has(to)) {\n      if (!TEMP_UNITS.has(from))\n        return `Error: \"${from}\" is not a temperature unit. Use C, F, or K.`\n      if (!TEMP_UNITS.has(to)) return `Error: \"${to}\" is not a temperature unit. Use C, F, or K.`\n      const result = fromKelvin(toKelvin(value, from as TempUnit), to as TempUnit)\n      const rounded = Number.parseFloat(result.toPrecision(10))\n      return `${value}${TEMP_LABELS[from as TempUnit]} = ${rounded}${TEMP_LABELS[to as TempUnit]}`\n    }\n\n    const fromDef = UNITS[from]\n    const toDef = UNITS[to]\n    if (!fromDef) return `Error: Unknown unit \"${from}\". Supported: ${ALL_UNIT_KEYS}`\n    if (!toDef) return `Error: Unknown unit \"${to}\". Supported: ${ALL_UNIT_KEYS}`\n    if (fromDef.category !== toDef.category) {\n      return `Error: Cannot convert \"${from}\" (${fromDef.category}) to \"${to}\" (${toDef.category}) — different categories.`\n    }\n\n    const inBase = value * fromDef.factor\n    const result = inBase / toDef.factor\n    const rounded = Number.parseFloat(result.toPrecision(10))\n    return `${value} ${fromDef.label} = ${rounded} ${toDef.label}`\n  },\n})\n"],"mappings":"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"}
+{"version":3,"file":"unit_conversion.cjs","names":[],"sources":["../../../src/batteries/tools/unit_conversion/index.ts"],"sourcesContent":["/**\n * Pre-constructed tools for converting values across common measurement units.\n *\n * @module @nhtio/adk/batteries/tools/unit_conversion\n *\n * @remarks\n * Pre-constructed bundled tools for the `unit_conversion` category. Import individually, the whole\n * category, or import every tool via `@nhtio/adk/batteries`.\n */\n\nimport { Tool } from '@nhtio/adk/common'\nimport { validator } from '@nhtio/validation'\nimport { bigScale, formatBig, DEFAULT_PRECISION } from '@nhtio/adk/lib/helpers/bignum'\n\ntype UnitDef = { category: string; factor: number; label: string }\n\nconst UNITS: Record<string, UnitDef> = {\n  // Length (base: metre)\n  m: { category: 'length', factor: 1, label: 'metres' },\n  km: { category: 'length', factor: 1000, label: 'kilometres' },\n  cm: { category: 'length', factor: 0.01, label: 'centimetres' },\n  mm: { category: 'length', factor: 0.001, label: 'millimetres' },\n  mi: { category: 'length', factor: 1609.344, label: 'miles' },\n  ft: { category: 'length', factor: 0.3048, label: 'feet' },\n  in: { category: 'length', factor: 0.0254, label: 'inches' },\n  yd: { category: 'length', factor: 0.9144, label: 'yards' },\n  nmi: { category: 'length', factor: 1852, label: 'nautical miles' },\n\n  // Mass (base: gram)\n  g: { category: 'mass', factor: 1, label: 'grams' },\n  kg: { category: 'mass', factor: 1000, label: 'kilograms' },\n  mg: { category: 'mass', factor: 0.001, label: 'milligrams' },\n  t: { category: 'mass', factor: 1_000_000, label: 'metric tons' },\n  lb: { category: 'mass', factor: 453.59237, label: 'pounds' },\n  oz: { category: 'mass', factor: 28.349523125, label: 'ounces' },\n  st: { category: 'mass', factor: 6350.29318, label: 'stone' },\n\n  // Volume (base: litre)\n  L: { category: 'volume', factor: 1, label: 'litres' },\n  mL: { category: 'volume', factor: 0.001, label: 'millilitres' },\n  m3: { category: 'volume', factor: 1000, label: 'cubic metres' },\n  cm3: { category: 'volume', factor: 0.001, label: 'cubic centimetres' },\n  gal: { category: 'volume', factor: 3.785411784, label: 'US gallons' },\n  qt: { category: 'volume', factor: 0.946352946, label: 'US quarts' },\n  pt: { category: 'volume', factor: 0.473176473, label: 'US pints' },\n  cup: { category: 'volume', factor: 0.2365882365, label: 'US cups' },\n  floz: { category: 'volume', factor: 0.029573529562, label: 'US fluid ounces' },\n  tbsp: { category: 'volume', factor: 0.014786764781, label: 'tablespoons' },\n  tsp: { category: 'volume', factor: 0.0049289215938, label: 'teaspoons' },\n\n  // Speed (base: m/s)\n  m_s: { category: 'speed', factor: 1, label: 'm/s' },\n  km_h: { category: 'speed', factor: 1 / 3.6, label: 'km/h' },\n  mph: { category: 'speed', factor: 0.44704, label: 'mph' },\n  kn: { category: 'speed', factor: 0.514444, label: 'knots' },\n  ft_s: { category: 'speed', factor: 0.3048, label: 'ft/s' },\n\n  // Area (base: m²)\n  m2: { category: 'area', factor: 1, label: 'm²' },\n  km2: { category: 'area', factor: 1_000_000, label: 'km²' },\n  cm2: { category: 'area', factor: 0.0001, label: 'cm²' },\n  mm2: { category: 'area', factor: 0.000001, label: 'mm²' },\n  ft2: { category: 'area', factor: 0.09290304, label: 'sq ft' },\n  in2: { category: 'area', factor: 0.00064516, label: 'sq in' },\n  yd2: { category: 'area', factor: 0.83612736, label: 'sq yd' },\n  acre: { category: 'area', factor: 4046.8564224, label: 'acres' },\n  ha: { category: 'area', factor: 10_000, label: 'hectares' },\n\n  // Data storage (base: bit)\n  bit: { category: 'data', factor: 1, label: 'bits' },\n  B: { category: 'data', factor: 8, label: 'bytes' },\n  KB: { category: 'data', factor: 8_000, label: 'kilobytes' },\n  MB: { category: 'data', factor: 8_000_000, label: 'megabytes' },\n  GB: { category: 'data', factor: 8_000_000_000, label: 'gigabytes' },\n  TB: { category: 'data', factor: 8_000_000_000_000, label: 'terabytes' },\n  KiB: { category: 'data', factor: 8 * 1024, label: 'kibibytes' },\n  MiB: { category: 'data', factor: 8 * 1024 ** 2, label: 'mebibytes' },\n  GiB: { category: 'data', factor: 8 * 1024 ** 3, label: 'gibibytes' },\n  TiB: { category: 'data', factor: 8 * 1024 ** 4, label: 'tebibytes' },\n\n  // Time (base: second)\n  ms: { category: 'time', factor: 0.001, label: 'milliseconds' },\n  s: { category: 'time', factor: 1, label: 'seconds' },\n  min: { category: 'time', factor: 60, label: 'minutes' },\n  h: { category: 'time', factor: 3600, label: 'hours' },\n  d: { category: 'time', factor: 86400, label: 'days' },\n  wk: { category: 'time', factor: 604800, label: 'weeks' },\n\n  // Energy (base: joule)\n  J: { category: 'energy', factor: 1, label: 'joules' },\n  kJ: { category: 'energy', factor: 1000, label: 'kilojoules' },\n  cal: { category: 'energy', factor: 4.184, label: 'calories' },\n  kcal: { category: 'energy', factor: 4184, label: 'kilocalories' },\n  Wh: { category: 'energy', factor: 3600, label: 'watt-hours' },\n  kWh: { category: 'energy', factor: 3_600_000, label: 'kilowatt-hours' },\n  BTU: { category: 'energy', factor: 1055.05585, label: 'BTU' },\n\n  // Pressure (base: pascal)\n  Pa: { category: 'pressure', factor: 1, label: 'pascals' },\n  kPa: { category: 'pressure', factor: 1000, label: 'kilopascals' },\n  MPa: { category: 'pressure', factor: 1_000_000, label: 'megapascals' },\n  bar: { category: 'pressure', factor: 100_000, label: 'bar' },\n  psi: { category: 'pressure', factor: 6894.757, label: 'psi' },\n  atm: { category: 'pressure', factor: 101325, label: 'atm' },\n  mmHg: { category: 'pressure', factor: 133.322, label: 'mmHg' },\n\n  // Angle (base: radian)\n  rad: { category: 'angle', factor: 1, label: 'radians' },\n  deg: { category: 'angle', factor: Math.PI / 180, label: 'degrees' },\n  grad: { category: 'angle', factor: Math.PI / 200, label: 'gradians' },\n}\n\nconst TEMP_UNITS = new Set(['C', 'F', 'K'])\ntype TempUnit = 'C' | 'F' | 'K'\nconst TEMP_LABELS: Record<TempUnit, string> = { C: '°C', F: '°F', K: 'K' }\n\nfunction toKelvin(value: number, unit: TempUnit): number {\n  if (unit === 'C') return value + 273.15\n  if (unit === 'F') return (value - 32) * (5 / 9) + 273.15\n  return value\n}\n\nfunction fromKelvin(kelvin: number, unit: TempUnit): number {\n  if (unit === 'C') return kelvin - 273.15\n  if (unit === 'F') return (kelvin - 273.15) * (9 / 5) + 32\n  return kelvin\n}\n\nconst ALL_UNIT_KEYS = [...Object.keys(UNITS), 'C', 'F', 'K'].join(', ')\n\n/**\n * Convert a numeric value between units of the same physical category.\n *\n * @remarks\n * Supported categories: length, mass, volume, temperature, speed, area, data, time, energy,\n * pressure, angle. Uses static conversion tables — no external data required. Temperature is\n * handled specially via a Kelvin intermediate to preserve precision across `C`/`F`/`K`.\n */\nexport const convertUnitTool = new Tool({\n  name: 'convert_unit',\n  description:\n    'Convert a numeric value between units of the same category (length, mass, volume, temperature, speed, area, data, time, energy, pressure, angle). Uses static lookup tables — no external data required.',\n  inputSchema: validator.object({\n    value: validator.number().required().description('Numeric value to convert'),\n    from: validator\n      .string()\n      .required()\n      .description(`Source unit key. Supported keys: ${ALL_UNIT_KEYS}`),\n    to: validator\n      .string()\n      .required()\n      .description('Target unit key (must be in the same category as source)'),\n    precision: validator\n      .number()\n      .default(DEFAULT_PRECISION)\n      .description(`Significant digits in the result (default: ${DEFAULT_PRECISION}).`),\n  }),\n  handler: async (args) => {\n    const { value, from, to, precision } = args as {\n      value: number\n      from: string\n      to: string\n      precision: number\n    }\n\n    if (TEMP_UNITS.has(from) || TEMP_UNITS.has(to)) {\n      if (!TEMP_UNITS.has(from))\n        return `Error: \"${from}\" is not a temperature unit. Use C, F, or K.`\n      if (!TEMP_UNITS.has(to)) return `Error: \"${to}\" is not a temperature unit. Use C, F, or K.`\n      // Temperatures are small bounded values (schema rejects |value| > 2^53), so float64 math\n      // is exact enough; only the display precision changes.\n      const kelvin = toKelvin(value, from as TempUnit)\n      // Reject physically impossible temperatures below absolute zero (0 K) rather than silently\n      // returning a nonsensical value like \"-1 K = -274.15 °C\". A tiny epsilon absorbs float noise.\n      if (kelvin < -1e-9) {\n        return `Error: ${value}${TEMP_LABELS[from as TempUnit]} is below absolute zero (0 K); not a physical temperature.`\n      }\n      const result = fromKelvin(kelvin, to as TempUnit)\n      const rounded = formatBig(result, precision)\n      return `${value}${TEMP_LABELS[from as TempUnit]} = ${rounded}${TEMP_LABELS[to as TempUnit]}`\n    }\n\n    const fromDef = UNITS[from]\n    const toDef = UNITS[to]\n    if (!fromDef) return `Error: Unknown unit \"${from}\". Supported: ${ALL_UNIT_KEYS}`\n    if (!toDef) return `Error: Unknown unit \"${to}\". Supported: ${ALL_UNIT_KEYS}`\n    if (fromDef.category !== toDef.category) {\n      return `Error: Cannot convert \"${from}\" (${fromDef.category}) to \"${to}\" (${toDef.category}) — different categories.`\n    }\n\n    // `value * fromFactor / toFactor` in BigNumber so huge ratios (e.g. TB→bit) don't overflow to\n    // Infinity, tiny ratios (e.g. in→km) don't underflow to 0, and safe integers keep full digits.\n    const result = bigScale(value, fromDef.factor, toDef.factor)\n    const rounded = formatBig(result, precision)\n    return `${value} ${fromDef.label} = ${rounded} ${toDef.label}`\n  },\n})\n"],"mappings":"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"}

package/batteries/tools/unit_conversion.mjs

@@ -1,5 +1,6 @@
-import { t as Tool } from "../../tool-CMhaDRNd.mjs";
-import "../../common-BT0nfCi9.mjs";
+import { t as Tool } from "../../tool-wMYMVl60.mjs";
+import "../../common-DYDUi99O.mjs";
+import { bigScale, formatBig } from "../../lib/helpers/bignum.mjs";
 import { validator } from "@nhtio/validation";
 //#region src/batteries/tools/unit_conversion/index.ts
 /**
@@ -423,15 +424,17 @@ var convertUnitTool = new Tool({
 	inputSchema: validator.object({
 		value: validator.number().required().description("Numeric value to convert"),
 		from: validator.string().required().description(`Source unit key. Supported keys: ${ALL_UNIT_KEYS}`),
-		to: validator.string().required().description("Target unit key (must be in the same category as source)")
+		to: validator.string().required().description("Target unit key (must be in the same category as source)"),
+		precision: validator.number().default(8).description(`Significant digits in the result (default: 8).`)
 	}),
 	handler: async (args) => {
-		const { value, from, to } = args;
+		const { value, from, to, precision } = args;
 		if (TEMP_UNITS.has(from) || TEMP_UNITS.has(to)) {
 			if (!TEMP_UNITS.has(from)) return `Error: "${from}" is not a temperature unit. Use C, F, or K.`;
 			if (!TEMP_UNITS.has(to)) return `Error: "${to}" is not a temperature unit. Use C, F, or K.`;
-			const result = fromKelvin(toKelvin(value, from), to);
-			const rounded = Number.parseFloat(result.toPrecision(10));
+			const kelvin = toKelvin(value, from);
+			if (kelvin < -1e-9) return `Error: ${value}${TEMP_LABELS[from]} is below absolute zero (0 K); not a physical temperature.`;
+			const rounded = formatBig(fromKelvin(kelvin, to), precision);
 			return `${value}${TEMP_LABELS[from]} = ${rounded}${TEMP_LABELS[to]}`;
 		}
 		const fromDef = UNITS[from];
@@ -439,8 +442,7 @@ var convertUnitTool = new Tool({
 		if (!fromDef) return `Error: Unknown unit "${from}". Supported: ${ALL_UNIT_KEYS}`;
 		if (!toDef) return `Error: Unknown unit "${to}". Supported: ${ALL_UNIT_KEYS}`;
 		if (fromDef.category !== toDef.category) return `Error: Cannot convert "${from}" (${fromDef.category}) to "${to}" (${toDef.category}) — different categories.`;
-		const result = value * fromDef.factor / toDef.factor;
-		const rounded = Number.parseFloat(result.toPrecision(10));
+		const rounded = formatBig(bigScale(value, fromDef.factor, toDef.factor), precision);
 		return `${value} ${fromDef.label} = ${rounded} ${toDef.label}`;
 	}
 });

package/batteries/tools/unit_conversion.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"unit_conversion.mjs","names":[],"sources":["../../../src/batteries/tools/unit_conversion/index.ts"],"sourcesContent":["/**\n * Pre-constructed tools for converting values across common measurement units.\n *\n * @module @nhtio/adk/batteries/tools/unit_conversion\n *\n * @remarks\n * Pre-constructed bundled tools for the `unit_conversion` category. Import individually, the whole\n * category, or import every tool via `@nhtio/adk/batteries`.\n */\n\nimport { Tool } from '@nhtio/adk/common'\nimport { validator } from '@nhtio/validation'\n\ntype UnitDef = { category: string; factor: number; label: string }\n\nconst UNITS: Record<string, UnitDef> = {\n  // Length (base: metre)\n  m: { category: 'length', factor: 1, label: 'metres' },\n  km: { category: 'length', factor: 1000, label: 'kilometres' },\n  cm: { category: 'length', factor: 0.01, label: 'centimetres' },\n  mm: { category: 'length', factor: 0.001, label: 'millimetres' },\n  mi: { category: 'length', factor: 1609.344, label: 'miles' },\n  ft: { category: 'length', factor: 0.3048, label: 'feet' },\n  in: { category: 'length', factor: 0.0254, label: 'inches' },\n  yd: { category: 'length', factor: 0.9144, label: 'yards' },\n  nmi: { category: 'length', factor: 1852, label: 'nautical miles' },\n\n  // Mass (base: gram)\n  g: { category: 'mass', factor: 1, label: 'grams' },\n  kg: { category: 'mass', factor: 1000, label: 'kilograms' },\n  mg: { category: 'mass', factor: 0.001, label: 'milligrams' },\n  t: { category: 'mass', factor: 1_000_000, label: 'metric tons' },\n  lb: { category: 'mass', factor: 453.59237, label: 'pounds' },\n  oz: { category: 'mass', factor: 28.349523125, label: 'ounces' },\n  st: { category: 'mass', factor: 6350.29318, label: 'stone' },\n\n  // Volume (base: litre)\n  L: { category: 'volume', factor: 1, label: 'litres' },\n  mL: { category: 'volume', factor: 0.001, label: 'millilitres' },\n  m3: { category: 'volume', factor: 1000, label: 'cubic metres' },\n  cm3: { category: 'volume', factor: 0.001, label: 'cubic centimetres' },\n  gal: { category: 'volume', factor: 3.785411784, label: 'US gallons' },\n  qt: { category: 'volume', factor: 0.946352946, label: 'US quarts' },\n  pt: { category: 'volume', factor: 0.473176473, label: 'US pints' },\n  cup: { category: 'volume', factor: 0.2365882365, label: 'US cups' },\n  floz: { category: 'volume', factor: 0.029573529562, label: 'US fluid ounces' },\n  tbsp: { category: 'volume', factor: 0.014786764781, label: 'tablespoons' },\n  tsp: { category: 'volume', factor: 0.0049289215938, label: 'teaspoons' },\n\n  // Speed (base: m/s)\n  m_s: { category: 'speed', factor: 1, label: 'm/s' },\n  km_h: { category: 'speed', factor: 1 / 3.6, label: 'km/h' },\n  mph: { category: 'speed', factor: 0.44704, label: 'mph' },\n  kn: { category: 'speed', factor: 0.514444, label: 'knots' },\n  ft_s: { category: 'speed', factor: 0.3048, label: 'ft/s' },\n\n  // Area (base: m²)\n  m2: { category: 'area', factor: 1, label: 'm²' },\n  km2: { category: 'area', factor: 1_000_000, label: 'km²' },\n  cm2: { category: 'area', factor: 0.0001, label: 'cm²' },\n  mm2: { category: 'area', factor: 0.000001, label: 'mm²' },\n  ft2: { category: 'area', factor: 0.09290304, label: 'sq ft' },\n  in2: { category: 'area', factor: 0.00064516, label: 'sq in' },\n  yd2: { category: 'area', factor: 0.83612736, label: 'sq yd' },\n  acre: { category: 'area', factor: 4046.8564224, label: 'acres' },\n  ha: { category: 'area', factor: 10_000, label: 'hectares' },\n\n  // Data storage (base: bit)\n  bit: { category: 'data', factor: 1, label: 'bits' },\n  B: { category: 'data', factor: 8, label: 'bytes' },\n  KB: { category: 'data', factor: 8_000, label: 'kilobytes' },\n  MB: { category: 'data', factor: 8_000_000, label: 'megabytes' },\n  GB: { category: 'data', factor: 8_000_000_000, label: 'gigabytes' },\n  TB: { category: 'data', factor: 8_000_000_000_000, label: 'terabytes' },\n  KiB: { category: 'data', factor: 8 * 1024, label: 'kibibytes' },\n  MiB: { category: 'data', factor: 8 * 1024 ** 2, label: 'mebibytes' },\n  GiB: { category: 'data', factor: 8 * 1024 ** 3, label: 'gibibytes' },\n  TiB: { category: 'data', factor: 8 * 1024 ** 4, label: 'tebibytes' },\n\n  // Time (base: second)\n  ms: { category: 'time', factor: 0.001, label: 'milliseconds' },\n  s: { category: 'time', factor: 1, label: 'seconds' },\n  min: { category: 'time', factor: 60, label: 'minutes' },\n  h: { category: 'time', factor: 3600, label: 'hours' },\n  d: { category: 'time', factor: 86400, label: 'days' },\n  wk: { category: 'time', factor: 604800, label: 'weeks' },\n\n  // Energy (base: joule)\n  J: { category: 'energy', factor: 1, label: 'joules' },\n  kJ: { category: 'energy', factor: 1000, label: 'kilojoules' },\n  cal: { category: 'energy', factor: 4.184, label: 'calories' },\n  kcal: { category: 'energy', factor: 4184, label: 'kilocalories' },\n  Wh: { category: 'energy', factor: 3600, label: 'watt-hours' },\n  kWh: { category: 'energy', factor: 3_600_000, label: 'kilowatt-hours' },\n  BTU: { category: 'energy', factor: 1055.05585, label: 'BTU' },\n\n  // Pressure (base: pascal)\n  Pa: { category: 'pressure', factor: 1, label: 'pascals' },\n  kPa: { category: 'pressure', factor: 1000, label: 'kilopascals' },\n  MPa: { category: 'pressure', factor: 1_000_000, label: 'megapascals' },\n  bar: { category: 'pressure', factor: 100_000, label: 'bar' },\n  psi: { category: 'pressure', factor: 6894.757, label: 'psi' },\n  atm: { category: 'pressure', factor: 101325, label: 'atm' },\n  mmHg: { category: 'pressure', factor: 133.322, label: 'mmHg' },\n\n  // Angle (base: radian)\n  rad: { category: 'angle', factor: 1, label: 'radians' },\n  deg: { category: 'angle', factor: Math.PI / 180, label: 'degrees' },\n  grad: { category: 'angle', factor: Math.PI / 200, label: 'gradians' },\n}\n\nconst TEMP_UNITS = new Set(['C', 'F', 'K'])\ntype TempUnit = 'C' | 'F' | 'K'\nconst TEMP_LABELS: Record<TempUnit, string> = { C: '°C', F: '°F', K: 'K' }\n\nfunction toKelvin(value: number, unit: TempUnit): number {\n  if (unit === 'C') return value + 273.15\n  if (unit === 'F') return (value - 32) * (5 / 9) + 273.15\n  return value\n}\n\nfunction fromKelvin(kelvin: number, unit: TempUnit): number {\n  if (unit === 'C') return kelvin - 273.15\n  if (unit === 'F') return (kelvin - 273.15) * (9 / 5) + 32\n  return kelvin\n}\n\nconst ALL_UNIT_KEYS = [...Object.keys(UNITS), 'C', 'F', 'K'].join(', ')\n\n/**\n * Convert a numeric value between units of the same physical category.\n *\n * @remarks\n * Supported categories: length, mass, volume, temperature, speed, area, data, time, energy,\n * pressure, angle. Uses static conversion tables — no external data required. Temperature is\n * handled specially via a Kelvin intermediate to preserve precision across `C`/`F`/`K`.\n */\nexport const convertUnitTool = new Tool({\n  name: 'convert_unit',\n  description:\n    'Convert a numeric value between units of the same category (length, mass, volume, temperature, speed, area, data, time, energy, pressure, angle). Uses static lookup tables — no external data required.',\n  inputSchema: validator.object({\n    value: validator.number().required().description('Numeric value to convert'),\n    from: validator\n      .string()\n      .required()\n      .description(`Source unit key. Supported keys: ${ALL_UNIT_KEYS}`),\n    to: validator\n      .string()\n      .required()\n      .description('Target unit key (must be in the same category as source)'),\n  }),\n  handler: async (args) => {\n    const { value, from, to } = args as { value: number; from: string; to: string }\n\n    if (TEMP_UNITS.has(from) || TEMP_UNITS.has(to)) {\n      if (!TEMP_UNITS.has(from))\n        return `Error: \"${from}\" is not a temperature unit. Use C, F, or K.`\n      if (!TEMP_UNITS.has(to)) return `Error: \"${to}\" is not a temperature unit. Use C, F, or K.`\n      const result = fromKelvin(toKelvin(value, from as TempUnit), to as TempUnit)\n      const rounded = Number.parseFloat(result.toPrecision(10))\n      return `${value}${TEMP_LABELS[from as TempUnit]} = ${rounded}${TEMP_LABELS[to as TempUnit]}`\n    }\n\n    const fromDef = UNITS[from]\n    const toDef = UNITS[to]\n    if (!fromDef) return `Error: Unknown unit \"${from}\". Supported: ${ALL_UNIT_KEYS}`\n    if (!toDef) return `Error: Unknown unit \"${to}\". Supported: ${ALL_UNIT_KEYS}`\n    if (fromDef.category !== toDef.category) {\n      return `Error: Cannot convert \"${from}\" (${fromDef.category}) to \"${to}\" (${toDef.category}) — different categories.`\n    }\n\n    const inBase = value * fromDef.factor\n    const result = inBase / toDef.factor\n    const rounded = Number.parseFloat(result.toPrecision(10))\n    return `${value} ${fromDef.label} = ${rounded} ${toDef.label}`\n  },\n})\n"],"mappings":"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"}
+{"version":3,"file":"unit_conversion.mjs","names":[],"sources":["../../../src/batteries/tools/unit_conversion/index.ts"],"sourcesContent":["/**\n * Pre-constructed tools for converting values across common measurement units.\n *\n * @module @nhtio/adk/batteries/tools/unit_conversion\n *\n * @remarks\n * Pre-constructed bundled tools for the `unit_conversion` category. Import individually, the whole\n * category, or import every tool via `@nhtio/adk/batteries`.\n */\n\nimport { Tool } from '@nhtio/adk/common'\nimport { validator } from '@nhtio/validation'\nimport { bigScale, formatBig, DEFAULT_PRECISION } from '@nhtio/adk/lib/helpers/bignum'\n\ntype UnitDef = { category: string; factor: number; label: string }\n\nconst UNITS: Record<string, UnitDef> = {\n  // Length (base: metre)\n  m: { category: 'length', factor: 1, label: 'metres' },\n  km: { category: 'length', factor: 1000, label: 'kilometres' },\n  cm: { category: 'length', factor: 0.01, label: 'centimetres' },\n  mm: { category: 'length', factor: 0.001, label: 'millimetres' },\n  mi: { category: 'length', factor: 1609.344, label: 'miles' },\n  ft: { category: 'length', factor: 0.3048, label: 'feet' },\n  in: { category: 'length', factor: 0.0254, label: 'inches' },\n  yd: { category: 'length', factor: 0.9144, label: 'yards' },\n  nmi: { category: 'length', factor: 1852, label: 'nautical miles' },\n\n  // Mass (base: gram)\n  g: { category: 'mass', factor: 1, label: 'grams' },\n  kg: { category: 'mass', factor: 1000, label: 'kilograms' },\n  mg: { category: 'mass', factor: 0.001, label: 'milligrams' },\n  t: { category: 'mass', factor: 1_000_000, label: 'metric tons' },\n  lb: { category: 'mass', factor: 453.59237, label: 'pounds' },\n  oz: { category: 'mass', factor: 28.349523125, label: 'ounces' },\n  st: { category: 'mass', factor: 6350.29318, label: 'stone' },\n\n  // Volume (base: litre)\n  L: { category: 'volume', factor: 1, label: 'litres' },\n  mL: { category: 'volume', factor: 0.001, label: 'millilitres' },\n  m3: { category: 'volume', factor: 1000, label: 'cubic metres' },\n  cm3: { category: 'volume', factor: 0.001, label: 'cubic centimetres' },\n  gal: { category: 'volume', factor: 3.785411784, label: 'US gallons' },\n  qt: { category: 'volume', factor: 0.946352946, label: 'US quarts' },\n  pt: { category: 'volume', factor: 0.473176473, label: 'US pints' },\n  cup: { category: 'volume', factor: 0.2365882365, label: 'US cups' },\n  floz: { category: 'volume', factor: 0.029573529562, label: 'US fluid ounces' },\n  tbsp: { category: 'volume', factor: 0.014786764781, label: 'tablespoons' },\n  tsp: { category: 'volume', factor: 0.0049289215938, label: 'teaspoons' },\n\n  // Speed (base: m/s)\n  m_s: { category: 'speed', factor: 1, label: 'm/s' },\n  km_h: { category: 'speed', factor: 1 / 3.6, label: 'km/h' },\n  mph: { category: 'speed', factor: 0.44704, label: 'mph' },\n  kn: { category: 'speed', factor: 0.514444, label: 'knots' },\n  ft_s: { category: 'speed', factor: 0.3048, label: 'ft/s' },\n\n  // Area (base: m²)\n  m2: { category: 'area', factor: 1, label: 'm²' },\n  km2: { category: 'area', factor: 1_000_000, label: 'km²' },\n  cm2: { category: 'area', factor: 0.0001, label: 'cm²' },\n  mm2: { category: 'area', factor: 0.000001, label: 'mm²' },\n  ft2: { category: 'area', factor: 0.09290304, label: 'sq ft' },\n  in2: { category: 'area', factor: 0.00064516, label: 'sq in' },\n  yd2: { category: 'area', factor: 0.83612736, label: 'sq yd' },\n  acre: { category: 'area', factor: 4046.8564224, label: 'acres' },\n  ha: { category: 'area', factor: 10_000, label: 'hectares' },\n\n  // Data storage (base: bit)\n  bit: { category: 'data', factor: 1, label: 'bits' },\n  B: { category: 'data', factor: 8, label: 'bytes' },\n  KB: { category: 'data', factor: 8_000, label: 'kilobytes' },\n  MB: { category: 'data', factor: 8_000_000, label: 'megabytes' },\n  GB: { category: 'data', factor: 8_000_000_000, label: 'gigabytes' },\n  TB: { category: 'data', factor: 8_000_000_000_000, label: 'terabytes' },\n  KiB: { category: 'data', factor: 8 * 1024, label: 'kibibytes' },\n  MiB: { category: 'data', factor: 8 * 1024 ** 2, label: 'mebibytes' },\n  GiB: { category: 'data', factor: 8 * 1024 ** 3, label: 'gibibytes' },\n  TiB: { category: 'data', factor: 8 * 1024 ** 4, label: 'tebibytes' },\n\n  // Time (base: second)\n  ms: { category: 'time', factor: 0.001, label: 'milliseconds' },\n  s: { category: 'time', factor: 1, label: 'seconds' },\n  min: { category: 'time', factor: 60, label: 'minutes' },\n  h: { category: 'time', factor: 3600, label: 'hours' },\n  d: { category: 'time', factor: 86400, label: 'days' },\n  wk: { category: 'time', factor: 604800, label: 'weeks' },\n\n  // Energy (base: joule)\n  J: { category: 'energy', factor: 1, label: 'joules' },\n  kJ: { category: 'energy', factor: 1000, label: 'kilojoules' },\n  cal: { category: 'energy', factor: 4.184, label: 'calories' },\n  kcal: { category: 'energy', factor: 4184, label: 'kilocalories' },\n  Wh: { category: 'energy', factor: 3600, label: 'watt-hours' },\n  kWh: { category: 'energy', factor: 3_600_000, label: 'kilowatt-hours' },\n  BTU: { category: 'energy', factor: 1055.05585, label: 'BTU' },\n\n  // Pressure (base: pascal)\n  Pa: { category: 'pressure', factor: 1, label: 'pascals' },\n  kPa: { category: 'pressure', factor: 1000, label: 'kilopascals' },\n  MPa: { category: 'pressure', factor: 1_000_000, label: 'megapascals' },\n  bar: { category: 'pressure', factor: 100_000, label: 'bar' },\n  psi: { category: 'pressure', factor: 6894.757, label: 'psi' },\n  atm: { category: 'pressure', factor: 101325, label: 'atm' },\n  mmHg: { category: 'pressure', factor: 133.322, label: 'mmHg' },\n\n  // Angle (base: radian)\n  rad: { category: 'angle', factor: 1, label: 'radians' },\n  deg: { category: 'angle', factor: Math.PI / 180, label: 'degrees' },\n  grad: { category: 'angle', factor: Math.PI / 200, label: 'gradians' },\n}\n\nconst TEMP_UNITS = new Set(['C', 'F', 'K'])\ntype TempUnit = 'C' | 'F' | 'K'\nconst TEMP_LABELS: Record<TempUnit, string> = { C: '°C', F: '°F', K: 'K' }\n\nfunction toKelvin(value: number, unit: TempUnit): number {\n  if (unit === 'C') return value + 273.15\n  if (unit === 'F') return (value - 32) * (5 / 9) + 273.15\n  return value\n}\n\nfunction fromKelvin(kelvin: number, unit: TempUnit): number {\n  if (unit === 'C') return kelvin - 273.15\n  if (unit === 'F') return (kelvin - 273.15) * (9 / 5) + 32\n  return kelvin\n}\n\nconst ALL_UNIT_KEYS = [...Object.keys(UNITS), 'C', 'F', 'K'].join(', ')\n\n/**\n * Convert a numeric value between units of the same physical category.\n *\n * @remarks\n * Supported categories: length, mass, volume, temperature, speed, area, data, time, energy,\n * pressure, angle. Uses static conversion tables — no external data required. Temperature is\n * handled specially via a Kelvin intermediate to preserve precision across `C`/`F`/`K`.\n */\nexport const convertUnitTool = new Tool({\n  name: 'convert_unit',\n  description:\n    'Convert a numeric value between units of the same category (length, mass, volume, temperature, speed, area, data, time, energy, pressure, angle). Uses static lookup tables — no external data required.',\n  inputSchema: validator.object({\n    value: validator.number().required().description('Numeric value to convert'),\n    from: validator\n      .string()\n      .required()\n      .description(`Source unit key. Supported keys: ${ALL_UNIT_KEYS}`),\n    to: validator\n      .string()\n      .required()\n      .description('Target unit key (must be in the same category as source)'),\n    precision: validator\n      .number()\n      .default(DEFAULT_PRECISION)\n      .description(`Significant digits in the result (default: ${DEFAULT_PRECISION}).`),\n  }),\n  handler: async (args) => {\n    const { value, from, to, precision } = args as {\n      value: number\n      from: string\n      to: string\n      precision: number\n    }\n\n    if (TEMP_UNITS.has(from) || TEMP_UNITS.has(to)) {\n      if (!TEMP_UNITS.has(from))\n        return `Error: \"${from}\" is not a temperature unit. Use C, F, or K.`\n      if (!TEMP_UNITS.has(to)) return `Error: \"${to}\" is not a temperature unit. Use C, F, or K.`\n      // Temperatures are small bounded values (schema rejects |value| > 2^53), so float64 math\n      // is exact enough; only the display precision changes.\n      const kelvin = toKelvin(value, from as TempUnit)\n      // Reject physically impossible temperatures below absolute zero (0 K) rather than silently\n      // returning a nonsensical value like \"-1 K = -274.15 °C\". A tiny epsilon absorbs float noise.\n      if (kelvin < -1e-9) {\n        return `Error: ${value}${TEMP_LABELS[from as TempUnit]} is below absolute zero (0 K); not a physical temperature.`\n      }\n      const result = fromKelvin(kelvin, to as TempUnit)\n      const rounded = formatBig(result, precision)\n      return `${value}${TEMP_LABELS[from as TempUnit]} = ${rounded}${TEMP_LABELS[to as TempUnit]}`\n    }\n\n    const fromDef = UNITS[from]\n    const toDef = UNITS[to]\n    if (!fromDef) return `Error: Unknown unit \"${from}\". Supported: ${ALL_UNIT_KEYS}`\n    if (!toDef) return `Error: Unknown unit \"${to}\". Supported: ${ALL_UNIT_KEYS}`\n    if (fromDef.category !== toDef.category) {\n      return `Error: Cannot convert \"${from}\" (${fromDef.category}) to \"${to}\" (${toDef.category}) — different categories.`\n    }\n\n    // `value * fromFactor / toFactor` in BigNumber so huge ratios (e.g. TB→bit) don't overflow to\n    // Infinity, tiny ratios (e.g. in→km) don't underflow to 0, and safe integers keep full digits.\n    const result = bigScale(value, fromDef.factor, toDef.factor)\n    const rounded = formatBig(result, precision)\n    return `${value} ${fromDef.label} = ${rounded} ${toDef.label}`\n  },\n})\n"],"mappings":"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"}

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

@@ -0,0 +1,186 @@
+/**
+ * RAG glue: turn web-search and web-scrape results into `Retrievable` records for a turn.
+ *
+ * @module @nhtio/adk/batteries/tools/web_retrieval
+ *
+ * @remarks
+ * The seam from "I searched / scraped something" to "it is in the turn as a `Retrievable`",
+ * shared by the SearXNG and Scrapper batteries. It is deliberately **decoupled** from the ADK
+ * core at runtime:
+ *
+ * - The converters are **pure** `(payload) => RawRetrievable[]` — they build plain data objects and
+ *   never instantiate a core class, so the module's only core coupling is erased `import type`.
+ * - The recommended spool-artifact type travels as an **open resolver**
+ *   ({@link @nhtio/adk/forge!ArtifactConstructorResolver}), never a closed string enum — a consumer's
+ *   future YAML/HTML `SpooledArtifact` subclass works with no change here. The converter hands the
+ *   recommendation to the caller's `spool` hook; the caller owns the actual class import.
+ * - The one helper that must construct a `Retrievable` ({@link storeRetrievables}) takes the
+ *   constructor via a **resolver** (constructor / sync / async / dynamic-import), exactly like the
+ *   vector battery's `createVectorStore` `client`.
+ *
+ * Web content is `'third-party-public'` by default — a definitional constant for open-web data
+ * (NOT inferred from the URL, which CONTRIBUTING Design Decision #12 forbids); override via
+ * `trustTier` when you know better.
+ */
+import type { SpooledArtifact } from "../../../spooled_artifact";
+import type { ArtifactConstructorResolver } from "../../../forge";
+import type { RawRetrievable, Retrievable, RetrievableTrustTier } from "../../../common";
+/** A constructor that builds a {@link @nhtio/adk!Retrievable} from a {@link @nhtio/adk!RawRetrievable}. */
+export type RetrievableCtor = new (raw: RawRetrievable) => Retrievable;
+/** A resolver of `T`: the value itself, or a (sync/async) thunk, optionally a module `{ default }`. */
+export type Resolver<T> = T | (() => T | {
+    default: T;
+}) | (() => Promise<T | {
+    default: T;
+}>);
+/**
+ * A reader-backed-artifact hook. Called by a converter for content that may be large; the
+ * converter passes the artifact constructor it **recommends** for this content (an open
+ * {@link @nhtio/adk/forge!ArtifactConstructorResolver}) so the caller can wrap with the right
+ * subclass — preserving its forged query tools — using the caller's own core import. Return a
+ * {@link @nhtio/adk!SpooledArtifact} to store the content reader-backed, or `undefined` to keep it
+ * inline as a string.
+ */
+export type SpoolHook = (id: string, text: string, recommended: ArtifactConstructorResolver) => SpooledArtifact | undefined;
+/** Options common to every converter. */
+export interface ToRetrievableOptions {
+    /**
+     * Trust tier for the produced records. Default `'third-party-public'` (web content is
+     * third-party by definition — this is a constant, not URL inference).
+     */
+    trustTier?: RetrievableTrustTier;
+    /** Semantic `kind` label, e.g. `'web-search-result'`, `'web-article'`, `'web-links'`. */
+    kind?: string;
+    /** Prefix for the stable, hashed record id (namespacing across sources). */
+    idPrefix?: string;
+    /** Optional reader-backed-artifact hook for large content. See {@link SpoolHook}. */
+    spool?: SpoolHook;
+}
+/**
+ * The artifact-resolver recommendations a caller may supply so the glue names no concrete class
+ * itself. Each converter asks for the relevant key; if the caller omits it, content stays inline.
+ */
+export interface ArtifactRecommendations {
+    /** Recommended for plain-text / HTML content (base `SpooledArtifact`). */
+    text?: ArtifactConstructorResolver;
+    /** Recommended for markdown content (`SpooledMarkdownArtifact`). */
+    markdown?: ArtifactConstructorResolver;
+    /** Recommended for JSON content (`SpooledJsonArtifact`). */
+    json?: ArtifactConstructorResolver;
+}
+/** Minimal structural shape of a SearXNG normalised result the converter reads. */
+export interface SearxngResultLike {
+    /** Result URL (becomes the record's `source`). */
+    url?: string;
+    /** Result title (joined into the inline content). */
+    title?: string;
+    /** Result snippet (joined into the inline content). */
+    content?: string;
+    /** Relevance score (clamped to `[0,1]` on the record). */
+    score?: number;
+}
+/** Minimal structural shape of a SearXNG normalised payload. */
+export interface SearxngPayloadLike {
+    /** The result list. */
+    results?: SearxngResultLike[];
+}
+/**
+ * Convert a SearXNG normalised payload into one {@link @nhtio/adk!RawRetrievable} per result.
+ *
+ * @remarks
+ * Snippets are short, so `content` stays an inline string (the `spool` hook, if any, is still
+ * offered the `text` recommendation). `source` is the result URL; `score` is clamped to `[0,1]`.
+ *
+ * @param payload - The SearXNG normalised payload (`{ results: [{ url, title, content, score }] }`).
+ * @param opts - Trust tier, kind, id prefix, optional spool hook.
+ * @param recommend - Optional artifact-resolver recommendations (the glue names no class itself).
+ * @returns One `RawRetrievable` per result.
+ */
+export declare const searxngResultsToRetrievables: (payload: SearxngPayloadLike, opts?: ToRetrievableOptions, recommend?: ArtifactRecommendations) => RawRetrievable[];
+/** Minimal structural shape of a Scrapper normalised article. */
+export interface ScrapperArticleLike {
+    /** The page URL (becomes the record's `source`). */
+    url?: string;
+    /** Article title. */
+    title?: string;
+    /** Article text with HTML stripped (the default content source). */
+    textContent?: string;
+    /** Processed article HTML (the `'content'` content source). */
+    content?: string;
+}
+/** Which article text field to use as the record content. */
+export type ArticleContentSource = 'textContent' | 'content';
+/** Options for {@link scrapperArticleToRetrievable}. */
+export interface ArticleToRetrievableOptions extends ToRetrievableOptions {
+    /** Which field to use as content (default `'textContent'`). `'content'` is HTML. */
+    contentSource?: ArticleContentSource;
+    /**
+     * Whether the chosen content is markdown (recommend `markdown`) rather than plain text.
+     * Default false. Use when an output pipeline rendered the article to markdown.
+     */
+    asMarkdown?: boolean;
+}
+/**
+ * Convert a Scrapper normalised article into a single {@link @nhtio/adk!RawRetrievable}.
+ *
+ * @remarks
+ * Long article text is exactly what a reader-backed {@link @nhtio/adk!SpooledArtifact} is for: pass a
+ * `spool` hook and the converter offers it the recommended artifact resolver (markdown when
+ * `asMarkdown`, else text/HTML) so the model gets the right forged query tools. Without a hook,
+ * content stays inline.
+ *
+ * @param article - The Scrapper normalised article.
+ * @param opts - Trust tier, kind, id prefix, content source, markdown flag, optional spool hook.
+ * @param recommend - Optional artifact-resolver recommendations.
+ * @returns A single `RawRetrievable`.
+ */
+export declare const scrapperArticleToRetrievable: (article: ScrapperArticleLike, opts?: ArticleToRetrievableOptions, recommend?: ArtifactRecommendations) => RawRetrievable;
+/** Minimal structural shape of a Scrapper normalised link. */
+export interface ScrapperLinkLike {
+    /** The link's target URL (becomes the record's `source`). */
+    url?: string;
+    /** The link's anchor text (becomes the record's content). */
+    text?: string;
+}
+/** Minimal structural shape of a Scrapper normalised links payload. */
+export interface ScrapperLinksLike {
+    /** The page URL the links were collected from. */
+    url?: string;
+    /** The collected links. */
+    links?: ScrapperLinkLike[];
+}
+/**
+ * Convert a Scrapper normalised links payload into one {@link @nhtio/adk!RawRetrievable} per link.
+ *
+ * @remarks
+ * Each link's `text` becomes the (inline) content and its `url` the `source`. Link text is short,
+ * so no spooling is applied.
+ *
+ * @param payload - The Scrapper normalised links payload (`{ links: [{ url, text }] }`).
+ * @param opts - Trust tier, kind, id prefix.
+ * @returns One `RawRetrievable` per link.
+ */
+export declare const scrapperLinksToRetrievables: (payload: ScrapperLinksLike, opts?: ToRetrievableOptions) => RawRetrievable[];
+/** The minimal context surface {@link storeRetrievables} needs. */
+export interface RetrievableStoreCtx {
+    /** Persist a single `Retrievable` into the turn (a `DispatchContext` method, or a stub). */
+    storeRetrievable: (v: Retrievable) => unknown | Promise<unknown>;
+}
+/**
+ * Construct {@link @nhtio/adk!Retrievable}s from `RawRetrievable`s and store each via `ctx`.
+ *
+ * @remarks
+ * This is the only function here that touches a core class, and it does so through an injected
+ * **resolver** (`deps.retrievable`) so the glue itself never value-imports `Retrievable`. Each
+ * record's `RawRetrievable` validation (including the required `trustTier`) fires at construction.
+ * For reader-backed content, the caller's `spool` hook will typically have used
+ * `ctx.storeRetrievableBytes` already; this helper just persists the records into the turn.
+ *
+ * @param ctx - Anything with a `storeRetrievable` method (a `DispatchContext`, or a stub).
+ * @param raws - The plain records from the converters.
+ * @param deps - `{ retrievable }`: the `Retrievable` constructor or a resolver of it.
+ * @returns The constructed `Retrievable` instances, in input order.
+ */
+export declare const storeRetrievables: (ctx: RetrievableStoreCtx, raws: RawRetrievable[], deps: {
+    retrievable: Resolver<RetrievableCtor>;
+}) => Promise<Retrievable[]>;