@nhtio/adk 0.1.0-master-f0aa531d

package/batteries/tools/color.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"color.mjs","names":[],"sources":["../../../src/batteries/tools/color/index.ts"],"sourcesContent":["/**\n * Pre-constructed tools for color conversion and palette-oriented calculations.\n *\n * @module @nhtio/adk/batteries/tools/color\n *\n * @remarks\n * Pre-constructed bundled tools for the `color` 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 RGB = { r: number; g: number; b: number }\ntype HSL = { h: number; s: number; l: number }\n\nfunction hexToRgb(hex: string): RGB | null {\n  const cleaned = hex.replace(/^#/, '')\n  let r: number\n  let g: number\n  let b: number\n\n  if (cleaned.length === 3) {\n    r = Number.parseInt(cleaned[0] + cleaned[0], 16)\n    g = Number.parseInt(cleaned[1] + cleaned[1], 16)\n    b = Number.parseInt(cleaned[2] + cleaned[2], 16)\n  } else if (cleaned.length === 6) {\n    r = Number.parseInt(cleaned.slice(0, 2), 16)\n    g = Number.parseInt(cleaned.slice(2, 4), 16)\n    b = Number.parseInt(cleaned.slice(4, 6), 16)\n  } else {\n    return null\n  }\n\n  if (Number.isNaN(r) || Number.isNaN(g) || Number.isNaN(b)) return null\n  return { r, g, b }\n}\n\nfunction parseRgbString(input: string): RGB | null {\n  const match = input.match(/^rgb\\(\\s*(\\d+)\\s*,\\s*(\\d+)\\s*,\\s*(\\d+)\\s*\\)$/i)\n  if (!match) return null\n  const r = Number.parseInt(match[1], 10)\n  const g = Number.parseInt(match[2], 10)\n  const b = Number.parseInt(match[3], 10)\n  if (r > 255 || g > 255 || b > 255) return null\n  return { r, g, b }\n}\n\nfunction parseHslString(input: string): HSL | null {\n  const match = input.match(/^hsl\\(\\s*(\\d+)\\s*,\\s*(\\d+)%?\\s*,\\s*(\\d+)%?\\s*\\)$/i)\n  if (!match) return null\n  return {\n    h: Number.parseInt(match[1], 10) % 360,\n    s: Math.min(100, Number.parseInt(match[2], 10)),\n    l: Math.min(100, Number.parseInt(match[3], 10)),\n  }\n}\n\nconst NAMED_COLORS: Record<string, string> = {\n  'black': '#000000',\n  'white': '#FFFFFF',\n  'transparent': '#FFFFFF',\n  'aqua': '#00FFFF',\n  'magenta': '#FF00FF',\n  'fuchsia': '#FF00FF',\n  'silver': '#C0C0C0',\n  'maroon': '#800000',\n  'olive': '#808000',\n  'navy': '#000080',\n  'coral': '#FF7F50',\n  'crimson': '#DC143C',\n  'gold': '#FFD700',\n  'ivory': '#FFFFF0',\n  'khaki': '#F0E68C',\n  'lavender': '#E6E6FA',\n  'plum': '#DDA0DD',\n  'salmon': '#FA8072',\n  'sienna': '#A0522D',\n  'tan': '#D2B48C',\n  'tomato': '#FF6347',\n  'turquoise': '#40E0D0',\n  'violet': '#EE82EE',\n  'wheat': '#F5DEB3',\n  'red': '#F44336',\n  'red-lighten-5': '#FFEBEE',\n  'red-lighten-4': '#FFCDD2',\n  'red-lighten-3': '#EF9A9A',\n  'red-lighten-2': '#E57373',\n  'red-lighten-1': '#EF5350',\n  'red-darken-1': '#E53935',\n  'red-darken-2': '#D32F2F',\n  'red-darken-3': '#C62828',\n  'red-darken-4': '#B71C1C',\n  'red-accent-1': '#FF8A80',\n  'red-accent-2': '#FF5252',\n  'red-accent-3': '#FF1744',\n  'red-accent-4': '#D50000',\n  'pink': '#E91E63',\n  'pink-lighten-5': '#FCE4EC',\n  'pink-lighten-4': '#F8BBD0',\n  'pink-lighten-3': '#F48FB1',\n  'pink-lighten-2': '#F06292',\n  'pink-lighten-1': '#EC407A',\n  'pink-darken-1': '#D81B60',\n  'pink-darken-2': '#C2185B',\n  'pink-darken-3': '#AD1457',\n  'pink-darken-4': '#880E4F',\n  'pink-accent-1': '#FF80AB',\n  'pink-accent-2': '#FF4081',\n  'pink-accent-3': '#F50057',\n  'pink-accent-4': '#C51162',\n  'purple': '#9C27B0',\n  'purple-lighten-5': '#F3E5F5',\n  'purple-lighten-4': '#E1BEE7',\n  'purple-lighten-3': '#CE93D8',\n  'purple-lighten-2': '#BA68C8',\n  'purple-lighten-1': '#AB47BC',\n  'purple-darken-1': '#8E24AA',\n  'purple-darken-2': '#7B1FA2',\n  'purple-darken-3': '#6A1B9A',\n  'purple-darken-4': '#4A148C',\n  'purple-accent-1': '#EA80FC',\n  'purple-accent-2': '#E040FB',\n  'purple-accent-3': '#D500F9',\n  'purple-accent-4': '#AA00FF',\n  'deep-purple': '#673AB7',\n  'deep-purple-lighten-5': '#EDE7F6',\n  'deep-purple-lighten-4': '#D1C4E9',\n  'deep-purple-lighten-3': '#B39DDB',\n  'deep-purple-lighten-2': '#9575CD',\n  'deep-purple-lighten-1': '#7E57C2',\n  'deep-purple-darken-1': '#5E35B1',\n  'deep-purple-darken-2': '#512DA8',\n  'deep-purple-darken-3': '#4527A0',\n  'deep-purple-darken-4': '#311B92',\n  'deep-purple-accent-1': '#B388FF',\n  'deep-purple-accent-2': '#7C4DFF',\n  'deep-purple-accent-3': '#651FFF',\n  'deep-purple-accent-4': '#6200EA',\n  'indigo': '#3F51B5',\n  'indigo-lighten-5': '#E8EAF6',\n  'indigo-lighten-4': '#C5CAE9',\n  'indigo-lighten-3': '#9FA8DA',\n  'indigo-lighten-2': '#7986CB',\n  'indigo-lighten-1': '#5C6BC0',\n  'indigo-darken-1': '#3949AB',\n  'indigo-darken-2': '#303F9F',\n  'indigo-darken-3': '#283593',\n  'indigo-darken-4': '#1A237E',\n  'indigo-accent-1': '#8C9EFF',\n  'indigo-accent-2': '#536DFE',\n  'indigo-accent-3': '#3D5AFE',\n  'indigo-accent-4': '#304FFE',\n  'blue': '#2196F3',\n  'blue-lighten-5': '#E3F2FD',\n  'blue-lighten-4': '#BBDEFB',\n  'blue-lighten-3': '#90CAF9',\n  'blue-lighten-2': '#64B5F6',\n  'blue-lighten-1': '#42A5F5',\n  'blue-darken-1': '#1E88E5',\n  'blue-darken-2': '#1976D2',\n  'blue-darken-3': '#1565C0',\n  'blue-darken-4': '#0D47A1',\n  'blue-accent-1': '#82B1FF',\n  'blue-accent-2': '#448AFF',\n  'blue-accent-3': '#2979FF',\n  'blue-accent-4': '#2962FF',\n  'light-blue': '#03A9F4',\n  'light-blue-lighten-5': '#E1F5FE',\n  'light-blue-lighten-4': '#B3E5FC',\n  'light-blue-lighten-3': '#81D4FA',\n  'light-blue-lighten-2': '#4FC3F7',\n  'light-blue-lighten-1': '#29B6F6',\n  'light-blue-darken-1': '#039BE5',\n  'light-blue-darken-2': '#0288D1',\n  'light-blue-darken-3': '#0277BD',\n  'light-blue-darken-4': '#01579B',\n  'light-blue-accent-1': '#80D8FF',\n  'light-blue-accent-2': '#40C4FF',\n  'light-blue-accent-3': '#00B0FF',\n  'light-blue-accent-4': '#0091EA',\n  'cyan': '#00BCD4',\n  'cyan-lighten-5': '#E0F7FA',\n  'cyan-lighten-4': '#B2EBF2',\n  'cyan-lighten-3': '#80DEEA',\n  'cyan-lighten-2': '#4DD0E1',\n  'cyan-lighten-1': '#26C6DA',\n  'cyan-darken-1': '#00ACC1',\n  'cyan-darken-2': '#0097A7',\n  'cyan-darken-3': '#00838F',\n  'cyan-darken-4': '#006064',\n  'cyan-accent-1': '#84FFFF',\n  'cyan-accent-2': '#18FFFF',\n  'cyan-accent-3': '#00E5FF',\n  'cyan-accent-4': '#00B8D4',\n  'teal': '#009688',\n  'teal-lighten-5': '#E0F2F1',\n  'teal-lighten-4': '#B2DFDB',\n  'teal-lighten-3': '#80CBC4',\n  'teal-lighten-2': '#4DB6AC',\n  'teal-lighten-1': '#26A69A',\n  'teal-darken-1': '#00897B',\n  'teal-darken-2': '#00796B',\n  'teal-darken-3': '#00695C',\n  'teal-darken-4': '#004D40',\n  'teal-accent-1': '#A7FFEB',\n  'teal-accent-2': '#64FFDA',\n  'teal-accent-3': '#1DE9B6',\n  'teal-accent-4': '#00BFA5',\n  'green': '#4CAF50',\n  'green-lighten-5': '#E8F5E9',\n  'green-lighten-4': '#C8E6C9',\n  'green-lighten-3': '#A5D6A7',\n  'green-lighten-2': '#81C784',\n  'green-lighten-1': '#66BB6A',\n  'green-darken-1': '#43A047',\n  'green-darken-2': '#388E3C',\n  'green-darken-3': '#2E7D32',\n  'green-darken-4': '#1B5E20',\n  'green-accent-1': '#B9F6CA',\n  'green-accent-2': '#69F0AE',\n  'green-accent-3': '#00E676',\n  'green-accent-4': '#00C853',\n  'light-green': '#8BC34A',\n  'light-green-lighten-5': '#F1F8E9',\n  'light-green-lighten-4': '#DCEDC8',\n  'light-green-lighten-3': '#C5E1A5',\n  'light-green-lighten-2': '#AED581',\n  'light-green-lighten-1': '#9CCC65',\n  'light-green-darken-1': '#7CB342',\n  'light-green-darken-2': '#689F38',\n  'light-green-darken-3': '#558B2F',\n  'light-green-darken-4': '#33691E',\n  'light-green-accent-1': '#CCFF90',\n  'light-green-accent-2': '#B2FF59',\n  'light-green-accent-3': '#76FF03',\n  'light-green-accent-4': '#64DD17',\n  'lime': '#CDDC39',\n  'lime-lighten-5': '#F9FBE7',\n  'lime-lighten-4': '#F0F4C3',\n  'lime-lighten-3': '#E6EE9C',\n  'lime-lighten-2': '#DCE775',\n  'lime-lighten-1': '#D4E157',\n  'lime-darken-1': '#C0CA33',\n  'lime-darken-2': '#AFB42B',\n  'lime-darken-3': '#9E9D24',\n  'lime-darken-4': '#827717',\n  'lime-accent-1': '#F4FF81',\n  'lime-accent-2': '#EEFF41',\n  'lime-accent-3': '#C6FF00',\n  'lime-accent-4': '#AEEA00',\n  'yellow': '#FFEB3B',\n  'yellow-lighten-5': '#FFFDE7',\n  'yellow-lighten-4': '#FFF9C4',\n  'yellow-lighten-3': '#FFF59D',\n  'yellow-lighten-2': '#FFF176',\n  'yellow-lighten-1': '#FFEE58',\n  'yellow-darken-1': '#FDD835',\n  'yellow-darken-2': '#FBC02D',\n  'yellow-darken-3': '#F9A825',\n  'yellow-darken-4': '#F57F17',\n  'yellow-accent-1': '#FFFF8D',\n  'yellow-accent-2': '#FFFF00',\n  'yellow-accent-3': '#FFEA00',\n  'yellow-accent-4': '#FFD600',\n  'amber': '#FFC107',\n  'amber-lighten-5': '#FFF8E1',\n  'amber-lighten-4': '#FFECB3',\n  'amber-lighten-3': '#FFE082',\n  'amber-lighten-2': '#FFD54F',\n  'amber-lighten-1': '#FFCA28',\n  'amber-darken-1': '#FFB300',\n  'amber-darken-2': '#FFA000',\n  'amber-darken-3': '#FF8F00',\n  'amber-darken-4': '#FF6F00',\n  'amber-accent-1': '#FFE57F',\n  'amber-accent-2': '#FFD740',\n  'amber-accent-3': '#FFC400',\n  'amber-accent-4': '#FFAB00',\n  'orange': '#FF9800',\n  'orange-lighten-5': '#FFF3E0',\n  'orange-lighten-4': '#FFE0B2',\n  'orange-lighten-3': '#FFCC80',\n  'orange-lighten-2': '#FFB74D',\n  'orange-lighten-1': '#FFA726',\n  'orange-darken-1': '#FB8C00',\n  'orange-darken-2': '#F57C00',\n  'orange-darken-3': '#EF6C00',\n  'orange-darken-4': '#E65100',\n  'orange-accent-1': '#FFD180',\n  'orange-accent-2': '#FFAB40',\n  'orange-accent-3': '#FF9100',\n  'orange-accent-4': '#FF6D00',\n  'deep-orange': '#FF5722',\n  'deep-orange-lighten-5': '#FBE9E7',\n  'deep-orange-lighten-4': '#FFCCBC',\n  'deep-orange-lighten-3': '#FFAB91',\n  'deep-orange-lighten-2': '#FF8A65',\n  'deep-orange-lighten-1': '#FF7043',\n  'deep-orange-darken-1': '#F4511E',\n  'deep-orange-darken-2': '#E64A19',\n  'deep-orange-darken-3': '#D84315',\n  'deep-orange-darken-4': '#BF360C',\n  'deep-orange-accent-1': '#FF9E80',\n  'deep-orange-accent-2': '#FF6E40',\n  'deep-orange-accent-3': '#FF3D00',\n  'deep-orange-accent-4': '#DD2C00',\n  'brown': '#795548',\n  'brown-lighten-5': '#EFEBE9',\n  'brown-lighten-4': '#D7CCC8',\n  'brown-lighten-3': '#BCAAA4',\n  'brown-lighten-2': '#A1887F',\n  'brown-lighten-1': '#8D6E63',\n  'brown-darken-1': '#6D4C41',\n  'brown-darken-2': '#5D4037',\n  'brown-darken-3': '#4E342E',\n  'brown-darken-4': '#3E2723',\n  'blue-grey': '#607D8B',\n  'blue-grey-lighten-5': '#ECEFF1',\n  'blue-grey-lighten-4': '#CFD8DC',\n  'blue-grey-lighten-3': '#B0BEC5',\n  'blue-grey-lighten-2': '#90A4AE',\n  'blue-grey-lighten-1': '#78909C',\n  'blue-grey-darken-1': '#546E7A',\n  'blue-grey-darken-2': '#455A64',\n  'blue-grey-darken-3': '#37474F',\n  'blue-grey-darken-4': '#263238',\n  'grey': '#9E9E9E',\n  'gray': '#9E9E9E',\n  'grey-lighten-5': '#FAFAFA',\n  'grey-lighten-4': '#F5F5F5',\n  'grey-lighten-3': '#EEEEEE',\n  'grey-lighten-2': '#E0E0E0',\n  'grey-lighten-1': '#BDBDBD',\n  'grey-darken-1': '#757575',\n  'grey-darken-2': '#616161',\n  'grey-darken-3': '#424242',\n  'grey-darken-4': '#212121',\n}\n\nfunction parseColor(input: string): RGB | null {\n  const trimmed = input.trim()\n  const lower = trimmed.toLowerCase()\n\n  if (NAMED_COLORS[lower]) {\n    return hexToRgb(NAMED_COLORS[lower])\n  }\n\n  if (trimmed.startsWith('#')) return hexToRgb(trimmed)\n  if (lower.startsWith('rgb(')) return parseRgbString(trimmed)\n  if (lower.startsWith('hsl(')) {\n    const hsl = parseHslString(trimmed)\n    return hsl ? hslToRgb(hsl) : null\n  }\n\n  return hexToRgb(trimmed)\n}\n\nfunction rgbToHex(rgb: RGB): string {\n  const toHex = (n: number) =>\n    Math.round(Math.max(0, Math.min(255, n)))\n      .toString(16)\n      .padStart(2, '0')\n  return `#${toHex(rgb.r)}${toHex(rgb.g)}${toHex(rgb.b)}`\n}\n\nfunction rgbToHsl(rgb: RGB): HSL {\n  const r = rgb.r / 255\n  const g = rgb.g / 255\n  const b = rgb.b / 255\n\n  const max = Math.max(r, g, b)\n  const min = Math.min(r, g, b)\n  const l = (max + min) / 2\n\n  if (max === min) return { h: 0, s: 0, l: Math.round(l * 100) }\n\n  const d = max - min\n  const s = l > 0.5 ? d / (2 - max - min) : d / (max + min)\n\n  let h = 0\n  if (max === r) h = ((g - b) / d + (g < b ? 6 : 0)) / 6\n  else if (max === g) h = ((b - r) / d + 2) / 6\n  else h = ((r - g) / d + 4) / 6\n\n  return {\n    h: Math.round(h * 360),\n    s: Math.round(s * 100),\n    l: Math.round(l * 100),\n  }\n}\n\nfunction hslToRgb(hsl: HSL): RGB {\n  const h = hsl.h / 360\n  const s = hsl.s / 100\n  const l = hsl.l / 100\n\n  if (s === 0) {\n    const v = Math.round(l * 255)\n    return { r: v, g: v, b: v }\n  }\n\n  const hue2rgb = (p: number, q: number, t: number) => {\n    if (t < 0) t += 1\n    if (t > 1) t -= 1\n    if (t < 1 / 6) return p + (q - p) * 6 * t\n    if (t < 1 / 2) return q\n    if (t < 2 / 3) return p + (q - p) * (2 / 3 - t) * 6\n    return p\n  }\n\n  const q = l < 0.5 ? l * (1 + s) : l + s - l * s\n  const p = 2 * l - q\n\n  return {\n    r: Math.round(hue2rgb(p, q, h + 1 / 3) * 255),\n    g: Math.round(hue2rgb(p, q, h) * 255),\n    b: Math.round(hue2rgb(p, q, h - 1 / 3) * 255),\n  }\n}\n\nfunction relativeLuminance(rgb: RGB): number {\n  const srgb = [rgb.r, rgb.g, rgb.b].map((c) => {\n    const s = c / 255\n    return s <= 0.03928 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4)\n  })\n  return 0.2126 * srgb[0] + 0.7152 * srgb[1] + 0.0722 * srgb[2]\n}\n\nfunction contrastRatio(c1: RGB, c2: RGB): number {\n  const l1 = relativeLuminance(c1)\n  const l2 = relativeLuminance(c2)\n  const lighter = Math.max(l1, l2)\n  const darker = Math.min(l1, l2)\n  return (lighter + 0.05) / (darker + 0.05)\n}\n\nfunction rotateHue(hsl: HSL, degrees: number): HSL {\n  return { h: (hsl.h + degrees + 360) % 360, s: hsl.s, l: hsl.l }\n}\n\nfunction formatColor(rgb: RGB): string {\n  const hex = rgbToHex(rgb)\n  const hsl = rgbToHsl(rgb)\n  return `${hex} / rgb(${rgb.r}, ${rgb.g}, ${rgb.b}) / hsl(${hsl.h}, ${hsl.s}%, ${hsl.l}%)`\n}\n\n/**\n * Compute the WCAG 2.1 contrast ratio between two colours.\n *\n * @remarks\n * Accepts hex (`#rgb`, `#rrggbb`), `rgb()`, `hsl()`, or one of the CSS / Material Design named\n * colours. Reports the ratio and pass/fail against WCAG AA and AAA at both normal and large text\n * sizes. If the foreground/background combination fails AA Normal (4.5:1), the tool suggests\n * lightened or darkened variants that would pass.\n */\nexport const colorContrastTool = new Tool({\n  name: 'color_contrast',\n  description:\n    'Check the contrast ratio between two colors for WCAG accessibility compliance. Reports the contrast ratio and pass/fail for WCAG AA and AAA levels.',\n  inputSchema: validator.object({\n    foreground: validator\n      .string()\n      .required()\n      .description('Foreground color (hex, rgb(), hsl(), or named color).'),\n    background: validator\n      .string()\n      .required()\n      .description('Background color (hex, rgb(), hsl(), or named color).'),\n  }),\n  handler: async (args) => {\n    const { foreground, background } = args as { foreground: string; background: string }\n    const fg = parseColor(foreground)\n    const bg = parseColor(background)\n\n    if (!fg) return `Error: could not parse foreground color \"${foreground}\".`\n    if (!bg) return `Error: could not parse background color \"${background}\".`\n\n    const ratio = contrastRatio(fg, bg)\n    const rounded = Math.round(ratio * 100) / 100\n\n    const aaLargeText = ratio >= 3\n    const aaNormalText = ratio >= 4.5\n    const aaaLargeText = ratio >= 4.5\n    const aaaNormalText = ratio >= 7\n\n    const lines = [\n      `Foreground: ${formatColor(fg)}`,\n      `Background: ${formatColor(bg)}`,\n      `Contrast ratio: ${rounded}:1`,\n      '',\n      'WCAG 2.1 compliance:',\n      `  AA  Normal text (4.5:1): ${aaNormalText ? 'PASS' : 'FAIL'}`,\n      `  AA  Large text  (3.0:1): ${aaLargeText ? 'PASS' : 'FAIL'}`,\n      `  AAA Normal text (7.0:1): ${aaaNormalText ? 'PASS' : 'FAIL'}`,\n      `  AAA Large text  (4.5:1): ${aaaLargeText ? 'PASS' : 'FAIL'}`,\n    ]\n\n    if (!aaNormalText) {\n      const fgHsl = rgbToHsl(fg)\n      const bgHsl = rgbToHsl(bg)\n      const fgLighter = fgHsl.l > bgHsl.l\n\n      const suggestions: string[] = []\n      if (fgLighter) {\n        const lighter = hslToRgb({ ...fgHsl, l: Math.min(100, fgHsl.l + 15) })\n        const darkerBg = hslToRgb({ ...bgHsl, l: Math.max(0, bgHsl.l - 15) })\n        if (contrastRatio(lighter, bg) >= 4.5) {\n          suggestions.push(\n            `  Lighten foreground to ${rgbToHex(lighter)} (ratio: ${Math.round(contrastRatio(lighter, bg) * 100) / 100}:1)`\n          )\n        }\n        if (contrastRatio(fg, darkerBg) >= 4.5) {\n          suggestions.push(\n            `  Darken background to ${rgbToHex(darkerBg)} (ratio: ${Math.round(contrastRatio(fg, darkerBg) * 100) / 100}:1)`\n          )\n        }\n      } else {\n        const darker = hslToRgb({ ...fgHsl, l: Math.max(0, fgHsl.l - 15) })\n        const lighterBg = hslToRgb({ ...bgHsl, l: Math.min(100, bgHsl.l + 15) })\n        if (contrastRatio(darker, bg) >= 4.5) {\n          suggestions.push(\n            `  Darken foreground to ${rgbToHex(darker)} (ratio: ${Math.round(contrastRatio(darker, bg) * 100) / 100}:1)`\n          )\n        }\n        if (contrastRatio(fg, lighterBg) >= 4.5) {\n          suggestions.push(\n            `  Lighten background to ${rgbToHex(lighterBg)} (ratio: ${Math.round(contrastRatio(fg, lighterBg) * 100) / 100}:1)`\n          )\n        }\n      }\n\n      if (suggestions.length > 0) {\n        lines.push('', 'Suggestions to reach AA Normal (4.5:1):')\n        lines.push(...suggestions)\n      }\n    }\n\n    return lines.join('\\n')\n  },\n})\n\n/**\n * Generate a colour palette from a base colour using a named harmony.\n *\n * @remarks\n * Supported schemes: `complementary`, `analogous`, `triadic`, `split-complementary`,\n * `monochromatic`. Each entry reports its hex, rgb, and hsl forms, plus the contrast ratio\n * relative to the base colour.\n */\nexport const colorSchemeTool = new Tool({\n  name: 'color_scheme',\n  description:\n    'Generate a color palette from a base color. Supports complementary, analogous, triadic, split-complementary, and monochromatic schemes.',\n  inputSchema: validator.object({\n    color: validator\n      .string()\n      .required()\n      .description('Base color (hex, rgb(), hsl(), or named color).'),\n    scheme: validator\n      .string()\n      .valid('complementary', 'analogous', 'triadic', 'split-complementary', 'monochromatic')\n      .required()\n      .description('Type of color scheme to generate.'),\n  }),\n  handler: async (args) => {\n    const { color, scheme } = args as {\n      color: string\n      scheme: 'complementary' | 'analogous' | 'triadic' | 'split-complementary' | 'monochromatic'\n    }\n    const rgb = parseColor(color)\n    if (!rgb) return `Error: could not parse color \"${color}\".`\n\n    const hsl = rgbToHsl(rgb)\n    const palette: { label: string; rgb: RGB }[] = [{ label: 'Base', rgb }]\n\n    switch (scheme) {\n      case 'complementary':\n        palette.push({ label: 'Complement', rgb: hslToRgb(rotateHue(hsl, 180)) })\n        break\n\n      case 'analogous':\n        palette.push({ label: 'Analogous -30', rgb: hslToRgb(rotateHue(hsl, -30)) })\n        palette.push({ label: 'Analogous +30', rgb: hslToRgb(rotateHue(hsl, 30)) })\n        break\n\n      case 'triadic':\n        palette.push({ label: 'Triadic +120', rgb: hslToRgb(rotateHue(hsl, 120)) })\n        palette.push({ label: 'Triadic +240', rgb: hslToRgb(rotateHue(hsl, 240)) })\n        break\n\n      case 'split-complementary':\n        palette.push({ label: 'Split +150', rgb: hslToRgb(rotateHue(hsl, 150)) })\n        palette.push({ label: 'Split +210', rgb: hslToRgb(rotateHue(hsl, 210)) })\n        break\n\n      case 'monochromatic':\n        palette.push({ label: 'Light', rgb: hslToRgb({ ...hsl, l: Math.min(100, hsl.l + 20) }) })\n        palette.push({ label: 'Lighter', rgb: hslToRgb({ ...hsl, l: Math.min(100, hsl.l + 35) }) })\n        palette.push({ label: 'Dark', rgb: hslToRgb({ ...hsl, l: Math.max(0, hsl.l - 20) }) })\n        palette.push({ label: 'Darker', rgb: hslToRgb({ ...hsl, l: Math.max(0, hsl.l - 35) }) })\n        break\n    }\n\n    const lines = [`Color scheme: ${scheme}`, '']\n    for (const entry of palette) {\n      lines.push(`${entry.label}: ${formatColor(entry.rgb)}`)\n    }\n\n    if (palette.length > 1) {\n      lines.push('', 'Contrast ratios with base:')\n      for (const entry of palette.slice(1)) {\n        const ratio = Math.round(contrastRatio(rgb, entry.rgb) * 100) / 100\n        lines.push(`  ${entry.label}: ${ratio}:1`)\n      }\n    }\n\n    return lines.join('\\n')\n  },\n})\n\n/**\n * Lighten or darken a colour by a percentage of HSL lightness.\n *\n * @remarks\n * `amount` is clamped to `[1, 100]`; `steps` is clamped to `[1, 10]`. With `steps > 1` the tool\n * emits a ramp of progressively-adjusted colours, useful for generating tint/shade scales.\n */\nexport const colorAdjustTool = new Tool({\n  name: 'color_adjust',\n  description:\n    'Lighten or darken a color by a specified amount. Returns the adjusted color in hex, rgb, and hsl formats. Can generate multiple steps for a tint/shade scale.',\n  inputSchema: validator.object({\n    color: validator\n      .string()\n      .required()\n      .description('Color to adjust (hex, rgb(), hsl(), or named color).'),\n    action: validator\n      .string()\n      .valid('lighten', 'darken')\n      .required()\n      .description('Whether to lighten or darken the color.'),\n    amount: validator\n      .number()\n      .default(15)\n      .description('Amount to adjust per step (1-100, percentage of lightness). Default: 15.'),\n    steps: validator\n      .number()\n      .default(1)\n      .description('Generate multiple steps of adjustment (1-10). Default: 1.'),\n  }),\n  handler: async (args) => {\n    const {\n      color,\n      action,\n      amount: rawAmount,\n      steps: rawSteps,\n    } = args as {\n      color: string\n      action: 'lighten' | 'darken'\n      amount: number\n      steps: number\n    }\n    const rgb = parseColor(color)\n    if (!rgb) return `Error: could not parse color \"${color}\".`\n\n    const amount = Math.max(1, Math.min(100, rawAmount))\n    const steps = Math.max(1, Math.min(10, rawSteps))\n    const hsl = rgbToHsl(rgb)\n\n    const lines = [`Original: ${formatColor(rgb)}`]\n\n    for (let i = 1; i <= steps; i++) {\n      const delta = amount * i\n      const newL = action === 'lighten' ? Math.min(100, hsl.l + delta) : Math.max(0, hsl.l - delta)\n      const adjusted = hslToRgb({ ...hsl, l: newL })\n      const label =\n        steps === 1\n          ? `${action === 'lighten' ? 'Lightened' : 'Darkened'} (${delta}%)`\n          : `Step ${i} (${action} ${delta}%)`\n      lines.push(`${label}: ${formatColor(adjusted)}`)\n    }\n\n    return lines.join('\\n')\n  },\n})\n"],"mappings":"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"}

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

@@ -0,0 +1,29 @@
+/**
+ * Pre-constructed tools for comparing primitive values, arrays, and ranges.
+ *
+ * @module @nhtio/adk/batteries/tools/comparison
+ *
+ * @remarks
+ * Pre-constructed bundled tools for the `comparison` category. Import individually, the whole
+ * category, or import every tool via `@nhtio/adk/batteries`.
+ */
+import { Tool } from "../../../common";
+/**
+ * Compare two values and return their relationship (`equal`, `greater_than`, `less_than`).
+ *
+ * @remarks
+ * Handles numbers, strings (lexicographic), booleans, ISO date strings, and null/undefined.
+ * Use `type_hint` to force a specific interpretation; the default `auto` infers from the
+ * values themselves.
+ */
+export declare const compareValuesTool: Tool<import("../../../common").SpooledArtifact>;
+/**
+ * Compare two JSON objects and report keys only in A, keys only in B, keys with matching
+ * values, and keys with differing values.
+ *
+ * @remarks
+ * Accepts JSON strings (not pre-parsed objects) so the schema can validate the input
+ * shape uniformly across providers. When `deep` is true (default), nested objects and arrays
+ * are compared structurally; when false, comparison reduces to JSON serialisation equality.
+ */
+export declare const compareRecordsTool: Tool<import("../../../common").SpooledArtifact>;

package/batteries/tools/comparison.cjs

@@ -0,0 +1,171 @@
+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");
+require("../../guards.cjs");
+let _nhtio_validation = require("@nhtio/validation");
+//#region src/batteries/tools/comparison/index.ts
+/**
+* Pre-constructed tools for comparing primitive values, arrays, and ranges.
+*
+* @module @nhtio/adk/batteries/tools/comparison
+*
+* @remarks
+* Pre-constructed bundled tools for the `comparison` category. Import individually, the whole
+* category, or import every tool via `@nhtio/adk/batteries`.
+*/
+function coerce(value) {
+	if (value === null || value === void 0) return null;
+	if (typeof value === "number" || typeof value === "boolean") return value;
+	const n = Number(value);
+	if (!Number.isNaN(n) && value.trim() !== "") return n;
+	return value;
+}
+function compareTwo(a, b) {
+	const ca = coerce(a);
+	const cb = coerce(b);
+	if (ca === null && cb === null) return 0;
+	if (ca === null) return -1;
+	if (cb === null) return 1;
+	if (typeof ca === "number" && typeof cb === "number") return ca - cb;
+	return String(ca).localeCompare(String(cb));
+}
+/**
+* Compare two values and return their relationship (`equal`, `greater_than`, `less_than`).
+*
+* @remarks
+* Handles numbers, strings (lexicographic), booleans, ISO date strings, and null/undefined.
+* Use `type_hint` to force a specific interpretation; the default `auto` infers from the
+* values themselves.
+*/
+var compareValuesTool = new require_tool.Tool({
+	name: "compare_values",
+	description: "Compare two values and return their relationship: equal, greater_than, less_than, or not_comparable. Handles numbers, strings (lexicographic), booleans, dates (ISO strings), null/undefined.",
+	inputSchema: _nhtio_validation.validator.object({
+		a: _nhtio_validation.validator.any().required().description("First value to compare"),
+		b: _nhtio_validation.validator.any().required().description("Second value to compare"),
+		type_hint: _nhtio_validation.validator.string().valid("auto", "string", "number", "date").default("auto").description("Force interpretation: \"auto\" detects, \"date\" parses ISO date strings, \"string\" compares lexicographically, \"number\" coerces to numbers (default: auto)"),
+		case_insensitive: _nhtio_validation.validator.boolean().default(false).description("For string comparisons: ignore case (default: false)")
+	}),
+	handler: async (args) => {
+		const { a: rawA, b: rawB, type_hint: typeHint, case_insensitive: ci } = args;
+		let av = rawA;
+		let bv = rawB;
+		try {
+			if (typeHint === "date") {
+				const da = new Date(av);
+				const db = new Date(bv);
+				if (Number.isNaN(da.getTime())) return `Error: Cannot parse "${av}" as a date.`;
+				if (Number.isNaN(db.getTime())) return `Error: Cannot parse "${bv}" as a date.`;
+				const diff = da.getTime() - db.getTime();
+				return `${diff === 0 ? "equal" : diff > 0 ? "greater_than" : "less_than"}\na = ${da.toISOString()}\nb = ${db.toISOString()}`;
+			}
+			if (typeHint === "number") {
+				const na = Number(av);
+				const nb = Number(bv);
+				if (Number.isNaN(na)) return `Error: Cannot convert "${av}" to a number.`;
+				if (Number.isNaN(nb)) return `Error: Cannot convert "${bv}" to a number.`;
+				const diff = na - nb;
+				return diff === 0 ? "equal" : diff > 0 ? "greater_than" : "less_than";
+			}
+			if (typeHint === "string") {
+				const sa = ci ? String(av).toLowerCase() : String(av);
+				const sb = ci ? String(bv).toLowerCase() : String(bv);
+				const cmp = sa.localeCompare(sb);
+				return cmp === 0 ? "equal" : cmp > 0 ? "greater_than" : "less_than";
+			}
+			if (ci && typeof av === "string" && typeof bv === "string") {
+				av = av.toLowerCase();
+				bv = bv.toLowerCase();
+			}
+			const cmp = compareTwo(av, bv);
+			return cmp === 0 ? "equal" : cmp > 0 ? "greater_than" : "less_than";
+		} catch (err) {
+			return `Error: ${require_tool_registry.isError(err) ? err.message : String(err)}`;
+		}
+	}
+});
+/**
+* Compare two JSON objects and report keys only in A, keys only in B, keys with matching
+* values, and keys with differing values.
+*
+* @remarks
+* Accepts JSON strings (not pre-parsed objects) so the schema can validate the input
+* shape uniformly across providers. When `deep` is true (default), nested objects and arrays
+* are compared structurally; when false, comparison reduces to JSON serialisation equality.
+*/
+var compareRecordsTool = new require_tool.Tool({
+	name: "compare_records",
+	description: "Compare two JSON objects and report: keys only in A, keys only in B, keys present in both with the same value, and keys present in both with different values.",
+	inputSchema: _nhtio_validation.validator.object({
+		record_a: _nhtio_validation.validator.string().required().description("First JSON object (as a string)"),
+		record_b: _nhtio_validation.validator.string().required().description("Second JSON object (as a string)"),
+		deep: _nhtio_validation.validator.boolean().default(true).description("Use deep equality for nested values (default: true). When false, compares by JSON serialization.")
+	}),
+	handler: async (args) => {
+		const { record_a: recordA, record_b: recordB, deep } = args;
+		let a;
+		let b;
+		try {
+			a = JSON.parse(recordA);
+		} catch {
+			return "Error: record_a is not valid JSON.";
+		}
+		try {
+			b = JSON.parse(recordB);
+		} catch {
+			return "Error: record_b is not valid JSON.";
+		}
+		if (typeof a !== "object" || a === null || Array.isArray(a)) return "Error: record_a must be a JSON object (not array or primitive).";
+		if (typeof b !== "object" || b === null || Array.isArray(b)) return "Error: record_b must be a JSON object (not array or primitive).";
+		function isEqual(x, y) {
+			if (!deep) return JSON.stringify(x) === JSON.stringify(y);
+			if (x === y) return true;
+			if (typeof x !== typeof y) return false;
+			if (x === null || y === null) return x === y;
+			if (Array.isArray(x) && Array.isArray(y)) {
+				if (x.length !== y.length) return false;
+				for (const [i, element] of x.entries()) if (!isEqual(element, y[i])) return false;
+				return true;
+			}
+			if (typeof x === "object" && typeof y === "object") {
+				const xk = Object.keys(x).sort();
+				const yk = Object.keys(y).sort();
+				if (JSON.stringify(xk) !== JSON.stringify(yk)) return false;
+				for (const k of xk) if (!isEqual(x[k], y[k])) return false;
+				return true;
+			}
+			return false;
+		}
+		const keysA = new Set(Object.keys(a));
+		const keysB = new Set(Object.keys(b));
+		const onlyInA = [];
+		const onlyInB = [];
+		const same = [];
+		const different = [];
+		for (const k of keysA) if (!keysB.has(k)) onlyInA.push(k);
+		else if (isEqual(a[k], b[k])) same.push(k);
+		else different.push({
+			key: k,
+			a: a[k],
+			b: b[k]
+		});
+		for (const k of keysB) if (!keysA.has(k)) onlyInB.push(k);
+		const lines = [];
+		if (onlyInA.length > 0) lines.push(`Only in A (${onlyInA.length}): ${onlyInA.join(", ")}`);
+		if (onlyInB.length > 0) lines.push(`Only in B (${onlyInB.length}): ${onlyInB.join(", ")}`);
+		if (same.length > 0) lines.push(`Same value (${same.length}): ${same.join(", ")}`);
+		if (different.length > 0) {
+			lines.push(`Different value (${different.length}):`);
+			for (const { key, a: av, b: bv } of different) lines.push(`  ${key}: A=${JSON.stringify(av)}, B=${JSON.stringify(bv)}`);
+		}
+		if (lines.length === 0) return "Records are identical.";
+		return lines.join("\n");
+	}
+});
+//#endregion
+exports.compareRecordsTool = compareRecordsTool;
+exports.compareValuesTool = compareValuesTool;
+
+//# sourceMappingURL=comparison.cjs.map

package/batteries/tools/comparison.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"comparison.cjs","names":[],"sources":["../../../src/batteries/tools/comparison/index.ts"],"sourcesContent":["/**\n * Pre-constructed tools for comparing primitive values, arrays, and ranges.\n *\n * @module @nhtio/adk/batteries/tools/comparison\n *\n * @remarks\n * Pre-constructed bundled tools for the `comparison` 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\ntype Primitive = string | number | boolean | null | undefined\n\nfunction coerce(value: Primitive): number | string | boolean | null {\n  if (value === null || value === undefined) return null\n  if (typeof value === 'number' || typeof value === 'boolean') return value\n  const n = Number(value)\n  if (!Number.isNaN(n) && value.trim() !== '') return n\n  return value\n}\n\nfunction compareTwo(a: Primitive, b: Primitive): number {\n  const ca = coerce(a)\n  const cb = coerce(b)\n  if (ca === null && cb === null) return 0\n  if (ca === null) return -1\n  if (cb === null) return 1\n  if (typeof ca === 'number' && typeof cb === 'number') return ca - cb\n  return String(ca).localeCompare(String(cb))\n}\n\n/**\n * Compare two values and return their relationship (`equal`, `greater_than`, `less_than`).\n *\n * @remarks\n * Handles numbers, strings (lexicographic), booleans, ISO date strings, and null/undefined.\n * Use `type_hint` to force a specific interpretation; the default `auto` infers from the\n * values themselves.\n */\nexport const compareValuesTool = new Tool({\n  name: 'compare_values',\n  description:\n    'Compare two values and return their relationship: equal, greater_than, less_than, or not_comparable. Handles numbers, strings (lexicographic), booleans, dates (ISO strings), null/undefined.',\n  inputSchema: validator.object({\n    a: validator.any().required().description('First value to compare'),\n    b: validator.any().required().description('Second value to compare'),\n    type_hint: validator\n      .string()\n      .valid('auto', 'string', 'number', 'date')\n      .default('auto')\n      .description(\n        'Force interpretation: \"auto\" detects, \"date\" parses ISO date strings, \"string\" compares lexicographically, \"number\" coerces to numbers (default: auto)'\n      ),\n    case_insensitive: validator\n      .boolean()\n      .default(false)\n      .description('For string comparisons: ignore case (default: false)'),\n  }),\n  handler: async (args) => {\n    const {\n      a: rawA,\n      b: rawB,\n      type_hint: typeHint,\n      case_insensitive: ci,\n    } = args as {\n      a: unknown\n      b: unknown\n      type_hint: string\n      case_insensitive: boolean\n    }\n\n    let av: unknown = rawA\n    let bv: unknown = rawB\n\n    try {\n      if (typeHint === 'date') {\n        const da = new Date(av as string)\n        const db = new Date(bv as string)\n        if (Number.isNaN(da.getTime())) return `Error: Cannot parse \"${av}\" as a date.`\n        if (Number.isNaN(db.getTime())) return `Error: Cannot parse \"${bv}\" as a date.`\n        const diff = da.getTime() - db.getTime()\n        const rel = diff === 0 ? 'equal' : diff > 0 ? 'greater_than' : 'less_than'\n        return `${rel}\\na = ${da.toISOString()}\\nb = ${db.toISOString()}`\n      }\n\n      if (typeHint === 'number') {\n        const na = Number(av)\n        const nb = Number(bv)\n        if (Number.isNaN(na)) return `Error: Cannot convert \"${av}\" to a number.`\n        if (Number.isNaN(nb)) return `Error: Cannot convert \"${bv}\" to a number.`\n        const diff = na - nb\n        return diff === 0 ? 'equal' : diff > 0 ? 'greater_than' : 'less_than'\n      }\n\n      if (typeHint === 'string') {\n        const sa = ci ? String(av).toLowerCase() : String(av)\n        const sb = ci ? String(bv).toLowerCase() : String(bv)\n        const cmp = sa.localeCompare(sb)\n        return cmp === 0 ? 'equal' : cmp > 0 ? 'greater_than' : 'less_than'\n      }\n\n      // auto\n      if (ci && typeof av === 'string' && typeof bv === 'string') {\n        av = av.toLowerCase()\n        bv = bv.toLowerCase()\n      }\n      const cmp = compareTwo(av as Primitive, bv as Primitive)\n      return cmp === 0 ? 'equal' : cmp > 0 ? 'greater_than' : 'less_than'\n    } catch (err) {\n      return `Error: ${isError(err) ? err.message : String(err)}`\n    }\n  },\n})\n\n/**\n * Compare two JSON objects and report keys only in A, keys only in B, keys with matching\n * values, and keys with differing values.\n *\n * @remarks\n * Accepts JSON strings (not pre-parsed objects) so the schema can validate the input\n * shape uniformly across providers. When `deep` is true (default), nested objects and arrays\n * are compared structurally; when false, comparison reduces to JSON serialisation equality.\n */\nexport const compareRecordsTool = new Tool({\n  name: 'compare_records',\n  description:\n    'Compare two JSON objects and report: keys only in A, keys only in B, keys present in both with the same value, and keys present in both with different values.',\n  inputSchema: validator.object({\n    record_a: validator.string().required().description('First JSON object (as a string)'),\n    record_b: validator.string().required().description('Second JSON object (as a string)'),\n    deep: validator\n      .boolean()\n      .default(true)\n      .description(\n        'Use deep equality for nested values (default: true). When false, compares by JSON serialization.'\n      ),\n  }),\n  handler: async (args) => {\n    const {\n      record_a: recordA,\n      record_b: recordB,\n      deep,\n    } = args as { record_a: string; record_b: string; deep: boolean }\n\n    let a: Record<string, unknown>\n    let b: Record<string, unknown>\n\n    try {\n      a = JSON.parse(recordA) as Record<string, unknown>\n    } catch {\n      return 'Error: record_a is not valid JSON.'\n    }\n    try {\n      b = JSON.parse(recordB) as Record<string, unknown>\n    } catch {\n      return 'Error: record_b is not valid JSON.'\n    }\n\n    if (typeof a !== 'object' || a === null || Array.isArray(a))\n      return 'Error: record_a must be a JSON object (not array or primitive).'\n    if (typeof b !== 'object' || b === null || Array.isArray(b))\n      return 'Error: record_b must be a JSON object (not array or primitive).'\n\n    function isEqual(x: unknown, y: unknown): boolean {\n      if (!deep) return JSON.stringify(x) === JSON.stringify(y)\n      if (x === y) return true\n      if (typeof x !== typeof y) return false\n      if (x === null || y === null) return x === y\n      if (Array.isArray(x) && Array.isArray(y)) {\n        if (x.length !== y.length) return false\n        for (const [i, element] of x.entries()) {\n          if (!isEqual(element, y[i])) return false\n        }\n        return true\n      }\n      if (typeof x === 'object' && typeof y === 'object') {\n        const xk = Object.keys(x as object).sort()\n        const yk = Object.keys(y as object).sort()\n        if (JSON.stringify(xk) !== JSON.stringify(yk)) return false\n        for (const k of xk) {\n          if (!isEqual((x as Record<string, unknown>)[k], (y as Record<string, unknown>)[k]))\n            return false\n        }\n        return true\n      }\n      return false\n    }\n\n    const keysA = new Set(Object.keys(a))\n    const keysB = new Set(Object.keys(b))\n\n    const onlyInA: string[] = []\n    const onlyInB: string[] = []\n    const same: string[] = []\n    const different: Array<{ key: string; a: unknown; b: unknown }> = []\n\n    for (const k of keysA) {\n      if (!keysB.has(k)) {\n        onlyInA.push(k)\n      } else if (isEqual(a[k], b[k])) {\n        same.push(k)\n      } else {\n        different.push({ key: k, a: a[k], b: b[k] })\n      }\n    }\n\n    for (const k of keysB) {\n      if (!keysA.has(k)) onlyInB.push(k)\n    }\n\n    const lines: string[] = []\n\n    if (onlyInA.length > 0) lines.push(`Only in A (${onlyInA.length}): ${onlyInA.join(', ')}`)\n    if (onlyInB.length > 0) lines.push(`Only in B (${onlyInB.length}): ${onlyInB.join(', ')}`)\n    if (same.length > 0) lines.push(`Same value (${same.length}): ${same.join(', ')}`)\n\n    if (different.length > 0) {\n      lines.push(`Different value (${different.length}):`)\n      for (const { key, a: av, b: bv } of different) {\n        lines.push(`  ${key}: A=${JSON.stringify(av)}, B=${JSON.stringify(bv)}`)\n      }\n    }\n\n    if (lines.length === 0) return 'Records are identical.'\n    return lines.join('\\n')\n  },\n})\n"],"mappings":"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"}

package/batteries/tools/comparison.mjs

@@ -0,0 +1,168 @@
+import { o as isError } from "../../tool_registry-DqLOyGyG.mjs";
+import "../../common-DeZaonK1.mjs";
+import { t as Tool } from "../../tool-D2WB1EA1.mjs";
+import "../../guards.mjs";
+import { validator } from "@nhtio/validation";
+//#region src/batteries/tools/comparison/index.ts
+/**
+* Pre-constructed tools for comparing primitive values, arrays, and ranges.
+*
+* @module @nhtio/adk/batteries/tools/comparison
+*
+* @remarks
+* Pre-constructed bundled tools for the `comparison` category. Import individually, the whole
+* category, or import every tool via `@nhtio/adk/batteries`.
+*/
+function coerce(value) {
+	if (value === null || value === void 0) return null;
+	if (typeof value === "number" || typeof value === "boolean") return value;
+	const n = Number(value);
+	if (!Number.isNaN(n) && value.trim() !== "") return n;
+	return value;
+}
+function compareTwo(a, b) {
+	const ca = coerce(a);
+	const cb = coerce(b);
+	if (ca === null && cb === null) return 0;
+	if (ca === null) return -1;
+	if (cb === null) return 1;
+	if (typeof ca === "number" && typeof cb === "number") return ca - cb;
+	return String(ca).localeCompare(String(cb));
+}
+/**
+* Compare two values and return their relationship (`equal`, `greater_than`, `less_than`).
+*
+* @remarks
+* Handles numbers, strings (lexicographic), booleans, ISO date strings, and null/undefined.
+* Use `type_hint` to force a specific interpretation; the default `auto` infers from the
+* values themselves.
+*/
+var compareValuesTool = new Tool({
+	name: "compare_values",
+	description: "Compare two values and return their relationship: equal, greater_than, less_than, or not_comparable. Handles numbers, strings (lexicographic), booleans, dates (ISO strings), null/undefined.",
+	inputSchema: validator.object({
+		a: validator.any().required().description("First value to compare"),
+		b: validator.any().required().description("Second value to compare"),
+		type_hint: validator.string().valid("auto", "string", "number", "date").default("auto").description("Force interpretation: \"auto\" detects, \"date\" parses ISO date strings, \"string\" compares lexicographically, \"number\" coerces to numbers (default: auto)"),
+		case_insensitive: validator.boolean().default(false).description("For string comparisons: ignore case (default: false)")
+	}),
+	handler: async (args) => {
+		const { a: rawA, b: rawB, type_hint: typeHint, case_insensitive: ci } = args;
+		let av = rawA;
+		let bv = rawB;
+		try {
+			if (typeHint === "date") {
+				const da = new Date(av);
+				const db = new Date(bv);
+				if (Number.isNaN(da.getTime())) return `Error: Cannot parse "${av}" as a date.`;
+				if (Number.isNaN(db.getTime())) return `Error: Cannot parse "${bv}" as a date.`;
+				const diff = da.getTime() - db.getTime();
+				return `${diff === 0 ? "equal" : diff > 0 ? "greater_than" : "less_than"}\na = ${da.toISOString()}\nb = ${db.toISOString()}`;
+			}
+			if (typeHint === "number") {
+				const na = Number(av);
+				const nb = Number(bv);
+				if (Number.isNaN(na)) return `Error: Cannot convert "${av}" to a number.`;
+				if (Number.isNaN(nb)) return `Error: Cannot convert "${bv}" to a number.`;
+				const diff = na - nb;
+				return diff === 0 ? "equal" : diff > 0 ? "greater_than" : "less_than";
+			}
+			if (typeHint === "string") {
+				const sa = ci ? String(av).toLowerCase() : String(av);
+				const sb = ci ? String(bv).toLowerCase() : String(bv);
+				const cmp = sa.localeCompare(sb);
+				return cmp === 0 ? "equal" : cmp > 0 ? "greater_than" : "less_than";
+			}
+			if (ci && typeof av === "string" && typeof bv === "string") {
+				av = av.toLowerCase();
+				bv = bv.toLowerCase();
+			}
+			const cmp = compareTwo(av, bv);
+			return cmp === 0 ? "equal" : cmp > 0 ? "greater_than" : "less_than";
+		} catch (err) {
+			return `Error: ${isError(err) ? err.message : String(err)}`;
+		}
+	}
+});
+/**
+* Compare two JSON objects and report keys only in A, keys only in B, keys with matching
+* values, and keys with differing values.
+*
+* @remarks
+* Accepts JSON strings (not pre-parsed objects) so the schema can validate the input
+* shape uniformly across providers. When `deep` is true (default), nested objects and arrays
+* are compared structurally; when false, comparison reduces to JSON serialisation equality.
+*/
+var compareRecordsTool = new Tool({
+	name: "compare_records",
+	description: "Compare two JSON objects and report: keys only in A, keys only in B, keys present in both with the same value, and keys present in both with different values.",
+	inputSchema: validator.object({
+		record_a: validator.string().required().description("First JSON object (as a string)"),
+		record_b: validator.string().required().description("Second JSON object (as a string)"),
+		deep: validator.boolean().default(true).description("Use deep equality for nested values (default: true). When false, compares by JSON serialization.")
+	}),
+	handler: async (args) => {
+		const { record_a: recordA, record_b: recordB, deep } = args;
+		let a;
+		let b;
+		try {
+			a = JSON.parse(recordA);
+		} catch {
+			return "Error: record_a is not valid JSON.";
+		}
+		try {
+			b = JSON.parse(recordB);
+		} catch {
+			return "Error: record_b is not valid JSON.";
+		}
+		if (typeof a !== "object" || a === null || Array.isArray(a)) return "Error: record_a must be a JSON object (not array or primitive).";
+		if (typeof b !== "object" || b === null || Array.isArray(b)) return "Error: record_b must be a JSON object (not array or primitive).";
+		function isEqual(x, y) {
+			if (!deep) return JSON.stringify(x) === JSON.stringify(y);
+			if (x === y) return true;
+			if (typeof x !== typeof y) return false;
+			if (x === null || y === null) return x === y;
+			if (Array.isArray(x) && Array.isArray(y)) {
+				if (x.length !== y.length) return false;
+				for (const [i, element] of x.entries()) if (!isEqual(element, y[i])) return false;
+				return true;
+			}
+			if (typeof x === "object" && typeof y === "object") {
+				const xk = Object.keys(x).sort();
+				const yk = Object.keys(y).sort();
+				if (JSON.stringify(xk) !== JSON.stringify(yk)) return false;
+				for (const k of xk) if (!isEqual(x[k], y[k])) return false;
+				return true;
+			}
+			return false;
+		}
+		const keysA = new Set(Object.keys(a));
+		const keysB = new Set(Object.keys(b));
+		const onlyInA = [];
+		const onlyInB = [];
+		const same = [];
+		const different = [];
+		for (const k of keysA) if (!keysB.has(k)) onlyInA.push(k);
+		else if (isEqual(a[k], b[k])) same.push(k);
+		else different.push({
+			key: k,
+			a: a[k],
+			b: b[k]
+		});
+		for (const k of keysB) if (!keysA.has(k)) onlyInB.push(k);
+		const lines = [];
+		if (onlyInA.length > 0) lines.push(`Only in A (${onlyInA.length}): ${onlyInA.join(", ")}`);
+		if (onlyInB.length > 0) lines.push(`Only in B (${onlyInB.length}): ${onlyInB.join(", ")}`);
+		if (same.length > 0) lines.push(`Same value (${same.length}): ${same.join(", ")}`);
+		if (different.length > 0) {
+			lines.push(`Different value (${different.length}):`);
+			for (const { key, a: av, b: bv } of different) lines.push(`  ${key}: A=${JSON.stringify(av)}, B=${JSON.stringify(bv)}`);
+		}
+		if (lines.length === 0) return "Records are identical.";
+		return lines.join("\n");
+	}
+});
+//#endregion
+export { compareRecordsTool, compareValuesTool };
+
+//# sourceMappingURL=comparison.mjs.map

package/batteries/tools/comparison.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"comparison.mjs","names":[],"sources":["../../../src/batteries/tools/comparison/index.ts"],"sourcesContent":["/**\n * Pre-constructed tools for comparing primitive values, arrays, and ranges.\n *\n * @module @nhtio/adk/batteries/tools/comparison\n *\n * @remarks\n * Pre-constructed bundled tools for the `comparison` 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\ntype Primitive = string | number | boolean | null | undefined\n\nfunction coerce(value: Primitive): number | string | boolean | null {\n  if (value === null || value === undefined) return null\n  if (typeof value === 'number' || typeof value === 'boolean') return value\n  const n = Number(value)\n  if (!Number.isNaN(n) && value.trim() !== '') return n\n  return value\n}\n\nfunction compareTwo(a: Primitive, b: Primitive): number {\n  const ca = coerce(a)\n  const cb = coerce(b)\n  if (ca === null && cb === null) return 0\n  if (ca === null) return -1\n  if (cb === null) return 1\n  if (typeof ca === 'number' && typeof cb === 'number') return ca - cb\n  return String(ca).localeCompare(String(cb))\n}\n\n/**\n * Compare two values and return their relationship (`equal`, `greater_than`, `less_than`).\n *\n * @remarks\n * Handles numbers, strings (lexicographic), booleans, ISO date strings, and null/undefined.\n * Use `type_hint` to force a specific interpretation; the default `auto` infers from the\n * values themselves.\n */\nexport const compareValuesTool = new Tool({\n  name: 'compare_values',\n  description:\n    'Compare two values and return their relationship: equal, greater_than, less_than, or not_comparable. Handles numbers, strings (lexicographic), booleans, dates (ISO strings), null/undefined.',\n  inputSchema: validator.object({\n    a: validator.any().required().description('First value to compare'),\n    b: validator.any().required().description('Second value to compare'),\n    type_hint: validator\n      .string()\n      .valid('auto', 'string', 'number', 'date')\n      .default('auto')\n      .description(\n        'Force interpretation: \"auto\" detects, \"date\" parses ISO date strings, \"string\" compares lexicographically, \"number\" coerces to numbers (default: auto)'\n      ),\n    case_insensitive: validator\n      .boolean()\n      .default(false)\n      .description('For string comparisons: ignore case (default: false)'),\n  }),\n  handler: async (args) => {\n    const {\n      a: rawA,\n      b: rawB,\n      type_hint: typeHint,\n      case_insensitive: ci,\n    } = args as {\n      a: unknown\n      b: unknown\n      type_hint: string\n      case_insensitive: boolean\n    }\n\n    let av: unknown = rawA\n    let bv: unknown = rawB\n\n    try {\n      if (typeHint === 'date') {\n        const da = new Date(av as string)\n        const db = new Date(bv as string)\n        if (Number.isNaN(da.getTime())) return `Error: Cannot parse \"${av}\" as a date.`\n        if (Number.isNaN(db.getTime())) return `Error: Cannot parse \"${bv}\" as a date.`\n        const diff = da.getTime() - db.getTime()\n        const rel = diff === 0 ? 'equal' : diff > 0 ? 'greater_than' : 'less_than'\n        return `${rel}\\na = ${da.toISOString()}\\nb = ${db.toISOString()}`\n      }\n\n      if (typeHint === 'number') {\n        const na = Number(av)\n        const nb = Number(bv)\n        if (Number.isNaN(na)) return `Error: Cannot convert \"${av}\" to a number.`\n        if (Number.isNaN(nb)) return `Error: Cannot convert \"${bv}\" to a number.`\n        const diff = na - nb\n        return diff === 0 ? 'equal' : diff > 0 ? 'greater_than' : 'less_than'\n      }\n\n      if (typeHint === 'string') {\n        const sa = ci ? String(av).toLowerCase() : String(av)\n        const sb = ci ? String(bv).toLowerCase() : String(bv)\n        const cmp = sa.localeCompare(sb)\n        return cmp === 0 ? 'equal' : cmp > 0 ? 'greater_than' : 'less_than'\n      }\n\n      // auto\n      if (ci && typeof av === 'string' && typeof bv === 'string') {\n        av = av.toLowerCase()\n        bv = bv.toLowerCase()\n      }\n      const cmp = compareTwo(av as Primitive, bv as Primitive)\n      return cmp === 0 ? 'equal' : cmp > 0 ? 'greater_than' : 'less_than'\n    } catch (err) {\n      return `Error: ${isError(err) ? err.message : String(err)}`\n    }\n  },\n})\n\n/**\n * Compare two JSON objects and report keys only in A, keys only in B, keys with matching\n * values, and keys with differing values.\n *\n * @remarks\n * Accepts JSON strings (not pre-parsed objects) so the schema can validate the input\n * shape uniformly across providers. When `deep` is true (default), nested objects and arrays\n * are compared structurally; when false, comparison reduces to JSON serialisation equality.\n */\nexport const compareRecordsTool = new Tool({\n  name: 'compare_records',\n  description:\n    'Compare two JSON objects and report: keys only in A, keys only in B, keys present in both with the same value, and keys present in both with different values.',\n  inputSchema: validator.object({\n    record_a: validator.string().required().description('First JSON object (as a string)'),\n    record_b: validator.string().required().description('Second JSON object (as a string)'),\n    deep: validator\n      .boolean()\n      .default(true)\n      .description(\n        'Use deep equality for nested values (default: true). When false, compares by JSON serialization.'\n      ),\n  }),\n  handler: async (args) => {\n    const {\n      record_a: recordA,\n      record_b: recordB,\n      deep,\n    } = args as { record_a: string; record_b: string; deep: boolean }\n\n    let a: Record<string, unknown>\n    let b: Record<string, unknown>\n\n    try {\n      a = JSON.parse(recordA) as Record<string, unknown>\n    } catch {\n      return 'Error: record_a is not valid JSON.'\n    }\n    try {\n      b = JSON.parse(recordB) as Record<string, unknown>\n    } catch {\n      return 'Error: record_b is not valid JSON.'\n    }\n\n    if (typeof a !== 'object' || a === null || Array.isArray(a))\n      return 'Error: record_a must be a JSON object (not array or primitive).'\n    if (typeof b !== 'object' || b === null || Array.isArray(b))\n      return 'Error: record_b must be a JSON object (not array or primitive).'\n\n    function isEqual(x: unknown, y: unknown): boolean {\n      if (!deep) return JSON.stringify(x) === JSON.stringify(y)\n      if (x === y) return true\n      if (typeof x !== typeof y) return false\n      if (x === null || y === null) return x === y\n      if (Array.isArray(x) && Array.isArray(y)) {\n        if (x.length !== y.length) return false\n        for (const [i, element] of x.entries()) {\n          if (!isEqual(element, y[i])) return false\n        }\n        return true\n      }\n      if (typeof x === 'object' && typeof y === 'object') {\n        const xk = Object.keys(x as object).sort()\n        const yk = Object.keys(y as object).sort()\n        if (JSON.stringify(xk) !== JSON.stringify(yk)) return false\n        for (const k of xk) {\n          if (!isEqual((x as Record<string, unknown>)[k], (y as Record<string, unknown>)[k]))\n            return false\n        }\n        return true\n      }\n      return false\n    }\n\n    const keysA = new Set(Object.keys(a))\n    const keysB = new Set(Object.keys(b))\n\n    const onlyInA: string[] = []\n    const onlyInB: string[] = []\n    const same: string[] = []\n    const different: Array<{ key: string; a: unknown; b: unknown }> = []\n\n    for (const k of keysA) {\n      if (!keysB.has(k)) {\n        onlyInA.push(k)\n      } else if (isEqual(a[k], b[k])) {\n        same.push(k)\n      } else {\n        different.push({ key: k, a: a[k], b: b[k] })\n      }\n    }\n\n    for (const k of keysB) {\n      if (!keysA.has(k)) onlyInB.push(k)\n    }\n\n    const lines: string[] = []\n\n    if (onlyInA.length > 0) lines.push(`Only in A (${onlyInA.length}): ${onlyInA.join(', ')}`)\n    if (onlyInB.length > 0) lines.push(`Only in B (${onlyInB.length}): ${onlyInB.join(', ')}`)\n    if (same.length > 0) lines.push(`Same value (${same.length}): ${same.join(', ')}`)\n\n    if (different.length > 0) {\n      lines.push(`Different value (${different.length}):`)\n      for (const { key, a: av, b: bv } of different) {\n        lines.push(`  ${key}: A=${JSON.stringify(av)}, B=${JSON.stringify(bv)}`)\n      }\n    }\n\n    if (lines.length === 0) return 'Records are identical.'\n    return lines.join('\\n')\n  },\n})\n"],"mappings":"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"}

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

@@ -0,0 +1,30 @@
+/**
+ * Pre-constructed tools for querying, filtering, grouping, and reshaping structured values.
+ *
+ * @module @nhtio/adk/batteries/tools/data_structure
+ *
+ * @remarks
+ * Pre-constructed bundled tools for the `data_structure` category. Import individually, the whole
+ * category, or import every tool via `@nhtio/adk/batteries`.
+ */
+import { Tool } from "../../../common";
+/**
+ * Apply a pipeline of operations to a JSON array or object.
+ *
+ * @remarks
+ * Operations are applied in order; each step transforms the output of the previous. Supported
+ * operations: `filter`, `sort`, `select_keys`, `pluck`, `slice`, `unique`, `unique_by`,
+ * `group_by`, `flatten`, `reverse`, `count`, `sum`, `avg`, `median`, `min`, `max`, `first`,
+ * `last`, `chunk`, `frequency_count`, `top_n`, `map_template`. Dot-notation paths are supported
+ * for nested key access in every operation that takes a `key` field.
+ */
+export declare const jsonTransformTool: Tool<import("../../../common").SpooledArtifact>;
+/**
+ * Perform set operations on two JSON arrays.
+ *
+ * @remarks
+ * Supported operations: `intersection`, `union`, `difference`, `symmetric_difference`,
+ * `is_member`, `is_subset`, `is_superset`. For arrays of objects, an optional `compare_key`
+ * narrows equality to a single property rather than deep structural comparison.
+ */
+export declare const setOperationsTool: Tool<import("../../../common").SpooledArtifact>;