@nhtio/adk 0.1.0-master-f0aa531d

package/batteries/tools/structured_data.mjs

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

package/batteries/tools/structured_data.mjs.map

@@ -0,0 +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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"}

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

@@ -0,0 +1,31 @@
+/**
+ * Pre-constructed tools for extracting counts, token estimates, and character statistics from text.
+ *
+ * @module @nhtio/adk/batteries/tools/text_analysis
+ *
+ * @remarks
+ * Pre-constructed bundled tools for the `text_analysis` category. Import individually, the whole
+ * category, or import every tool via `@nhtio/adk/batteries`.
+ */
+import { Tool, SpooledJsonArtifact } from "../../../common";
+/**
+ * Analyze text and return statistics as a JSON document.
+ *
+ * @remarks
+ * Reports character counts (with and without spaces), word/sentence/paragraph/line counts,
+ * unique word count, average word length, a rough token estimate (4 chars/token), and a set
+ * of character-class booleans (`is_all_alpha`, `is_all_ascii`, etc.).
+ *
+ * Output is JSON, so the artifact constructor is set to {@link @nhtio/adk!SpooledJsonArtifact} — consumer
+ * code can read the result back as a parsed record without re-parsing.
+ */
+export declare const textAnalyzeTool: Tool<SpooledJsonArtifact<unknown>>;
+/**
+ * Operate on text treated as a list of lines.
+ *
+ * @remarks
+ * Operations: `sort`, `sort_desc`, `reverse`, `deduplicate`, `filter_empty`, `trim_each`,
+ * `number` (prefix each line with `1.`, `2.`, …), `count`. Sort and deduplicate respect the
+ * optional `case_insensitive` flag.
+ */
+export declare const textLinesTool: Tool<import("../../../common").SpooledArtifact>;

package/batteries/tools/text_analysis.cjs

@@ -0,0 +1,120 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+require("../../chunk-KmRHZBOW.js");
+require("../../common-Od8edUXU.js");
+const require_tool = require("../../tool-COSeH8I6.js");
+const require_spooled_markdown_artifact = require("../../spooled_markdown_artifact-RRB113sy.js");
+let _nhtio_validation = require("@nhtio/validation");
+//#region src/batteries/tools/text_analysis/index.ts
+/**
+* Pre-constructed tools for extracting counts, token estimates, and character statistics from text.
+*
+* @module @nhtio/adk/batteries/tools/text_analysis
+*
+* @remarks
+* Pre-constructed bundled tools for the `text_analysis` category. Import individually, the whole
+* category, or import every tool via `@nhtio/adk/batteries`.
+*/
+/**
+* Analyze text and return statistics as a JSON document.
+*
+* @remarks
+* Reports character counts (with and without spaces), word/sentence/paragraph/line counts,
+* unique word count, average word length, a rough token estimate (4 chars/token), and a set
+* of character-class booleans (`is_all_alpha`, `is_all_ascii`, etc.).
+*
+* Output is JSON, so the artifact constructor is set to {@link @nhtio/adk!SpooledJsonArtifact} — consumer
+* code can read the result back as a parsed record without re-parsing.
+*/
+var textAnalyzeTool = new require_tool.Tool({
+	name: "text_analyze",
+	description: "Analyze text and return statistics: character counts, word/sentence/paragraph/line counts, unique word count, average word length, token estimate, and character-set properties.",
+	inputSchema: _nhtio_validation.validator.object({ text: _nhtio_validation.validator.string().required().description("The text to analyze") }),
+	artifactConstructor: () => require_spooled_markdown_artifact.SpooledJsonArtifact,
+	handler: async (args) => {
+		const { text } = args;
+		const charCount = text.length;
+		const charCountNoSpaces = text.replace(/\s/g, "").length;
+		const words = text.trim() === "" ? [] : text.trim().split(/\s+/);
+		const wordCount = words.length;
+		const sentenceMatches = text.match(/[.!?]+(?:\s|$)/g);
+		const sentenceCount = sentenceMatches ? sentenceMatches.length : text.trim().length > 0 ? 1 : 0;
+		const paragraphCount = text.split(/\n[ \t]*\n/).filter((p) => p.trim().length > 0).length || (text.trim().length > 0 ? 1 : 0);
+		const lineCount = text === "" ? 0 : text.split("\n").length;
+		const tokenEstimate = Math.ceil(text.length / 4);
+		const uniqueWordCount = new Set(words.map((w) => w.toLowerCase().replace(/[^a-z0-9]/g, "")).filter(Boolean)).size;
+		const totalWordLen = words.reduce((sum, w) => sum + w.length, 0);
+		const avgWordLength = wordCount > 0 ? Number.parseFloat((totalWordLen / wordCount).toFixed(2)) : 0;
+		const isAllAlpha = text.trim().length > 0 && /^[a-zA-Z\s]*$/.test(text);
+		const isAllNumeric = /^\d+$/.test(text.trim());
+		const isAllAlphanumeric = text.trim().length > 0 && /^[a-zA-Z0-9\s]*$/.test(text);
+		const isAllAscii = [...text].every((c) => c.charCodeAt(0) < 128);
+		const isAllLowercase = text === text.toLowerCase() && /[a-z]/.test(text);
+		const isAllUppercase = text === text.toUpperCase() && /[A-Z]/.test(text);
+		return JSON.stringify({
+			char_count: charCount,
+			char_count_no_spaces: charCountNoSpaces,
+			word_count: wordCount,
+			unique_word_count: uniqueWordCount,
+			sentence_count: sentenceCount,
+			paragraph_count: paragraphCount,
+			line_count: lineCount,
+			avg_word_length: avgWordLength,
+			token_estimate: tokenEstimate,
+			is_all_alpha: isAllAlpha,
+			is_all_numeric: isAllNumeric,
+			is_all_alphanumeric: isAllAlphanumeric,
+			is_all_ascii: isAllAscii,
+			is_all_lowercase: isAllLowercase,
+			is_all_uppercase: isAllUppercase,
+			has_unicode: !isAllAscii
+		}, null, 2);
+	}
+});
+/**
+* Operate on text treated as a list of lines.
+*
+* @remarks
+* Operations: `sort`, `sort_desc`, `reverse`, `deduplicate`, `filter_empty`, `trim_each`,
+* `number` (prefix each line with `1.`, `2.`, …), `count`. Sort and deduplicate respect the
+* optional `case_insensitive` flag.
+*/
+var textLinesTool = new require_tool.Tool({
+	name: "text_lines",
+	description: "Perform operations on text treated as a list of lines: sort, deduplicate, reverse, filter empty lines, trim each line, number each line, or count.",
+	inputSchema: _nhtio_validation.validator.object({
+		text: _nhtio_validation.validator.string().required().description("Multi-line text to process"),
+		operation: _nhtio_validation.validator.string().valid("sort", "sort_desc", "reverse", "deduplicate", "filter_empty", "trim_each", "number", "count").required().description("Operation to apply to lines"),
+		case_insensitive: _nhtio_validation.validator.boolean().default(false).description("For sort / deduplicate: ignore case (default: false)")
+	}),
+	handler: async (args) => {
+		const { text, operation, case_insensitive: ci } = args;
+		const lines = text.split("\n");
+		switch (operation) {
+			case "sort": return [...lines].sort((a, b) => (ci ? a.toLowerCase() : a).localeCompare(ci ? b.toLowerCase() : b)).join("\n");
+			case "sort_desc": return [...lines].sort((a, b) => (ci ? b.toLowerCase() : b).localeCompare(ci ? a.toLowerCase() : a)).join("\n");
+			case "reverse": return [...lines].reverse().join("\n");
+			case "deduplicate": {
+				const seen = /* @__PURE__ */ new Set();
+				return lines.filter((line) => {
+					const key = ci ? line.toLowerCase() : line;
+					if (seen.has(key)) return false;
+					seen.add(key);
+					return true;
+				}).join("\n");
+			}
+			case "filter_empty": return lines.filter((l) => l.trim() !== "").join("\n");
+			case "trim_each": return lines.map((l) => l.trim()).join("\n");
+			case "number": return lines.map((l, i) => `${i + 1}. ${l}`).join("\n");
+			case "count": {
+				const nonEmpty = lines.filter((l) => l.trim() !== "").length;
+				return `${lines.length} lines (${nonEmpty} non-empty, ${lines.length - nonEmpty} empty)`;
+			}
+			default: return `Error: Unknown operation "${operation}".`;
+		}
+	}
+});
+//#endregion
+exports.textAnalyzeTool = textAnalyzeTool;
+exports.textLinesTool = textLinesTool;
+
+//# sourceMappingURL=text_analysis.cjs.map

package/batteries/tools/text_analysis.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"text_analysis.cjs","names":[],"sources":["../../../src/batteries/tools/text_analysis/index.ts"],"sourcesContent":["/**\n * Pre-constructed tools for extracting counts, token estimates, and character statistics from text.\n *\n * @module @nhtio/adk/batteries/tools/text_analysis\n *\n * @remarks\n * Pre-constructed bundled tools for the `text_analysis` category. Import individually, the whole\n * category, or import every tool via `@nhtio/adk/batteries`.\n */\n\nimport { validator } from '@nhtio/validation'\nimport { Tool, SpooledJsonArtifact } from '@nhtio/adk/common'\n\n/**\n * Analyze text and return statistics as a JSON document.\n *\n * @remarks\n * Reports character counts (with and without spaces), word/sentence/paragraph/line counts,\n * unique word count, average word length, a rough token estimate (4 chars/token), and a set\n * of character-class booleans (`is_all_alpha`, `is_all_ascii`, etc.).\n *\n * Output is JSON, so the artifact constructor is set to {@link @nhtio/adk!SpooledJsonArtifact} — consumer\n * code can read the result back as a parsed record without re-parsing.\n */\nexport const textAnalyzeTool = new Tool({\n  name: 'text_analyze',\n  description:\n    'Analyze text and return statistics: character counts, word/sentence/paragraph/line counts, unique word count, average word length, token estimate, and character-set properties.',\n  inputSchema: validator.object({\n    text: validator.string().required().description('The text to analyze'),\n  }),\n  artifactConstructor: () => SpooledJsonArtifact,\n  handler: async (args) => {\n    const { text } = args as { text: string }\n\n    const charCount = text.length\n    const charCountNoSpaces = text.replace(/\\s/g, '').length\n\n    const words = text.trim() === '' ? [] : text.trim().split(/\\s+/)\n    const wordCount = words.length\n\n    const sentenceMatches = text.match(/[.!?]+(?:\\s|$)/g)\n    const sentenceCount = sentenceMatches ? sentenceMatches.length : text.trim().length > 0 ? 1 : 0\n\n    const paragraphs = text.split(/\\n[ \\t]*\\n/).filter((p) => p.trim().length > 0)\n    const paragraphCount = paragraphs.length || (text.trim().length > 0 ? 1 : 0)\n\n    const lineCount = text === '' ? 0 : text.split('\\n').length\n\n    const tokenEstimate = Math.ceil(text.length / 4)\n\n    const uniqueWords = new Set(\n      words.map((w) => w.toLowerCase().replace(/[^a-z0-9]/g, '')).filter(Boolean)\n    )\n    const uniqueWordCount = uniqueWords.size\n\n    const totalWordLen = words.reduce((sum, w) => sum + w.length, 0)\n    const avgWordLength =\n      wordCount > 0 ? Number.parseFloat((totalWordLen / wordCount).toFixed(2)) : 0\n\n    const isAllAlpha = text.trim().length > 0 && /^[a-zA-Z\\s]*$/.test(text)\n    const isAllNumeric = /^\\d+$/.test(text.trim())\n    const isAllAlphanumeric = text.trim().length > 0 && /^[a-zA-Z0-9\\s]*$/.test(text)\n    const isAllAscii = [...text].every((c) => c.charCodeAt(0) < 128)\n    const isAllLowercase = text === text.toLowerCase() && /[a-z]/.test(text)\n    const isAllUppercase = text === text.toUpperCase() && /[A-Z]/.test(text)\n\n    return JSON.stringify(\n      {\n        char_count: charCount,\n        char_count_no_spaces: charCountNoSpaces,\n        word_count: wordCount,\n        unique_word_count: uniqueWordCount,\n        sentence_count: sentenceCount,\n        paragraph_count: paragraphCount,\n        line_count: lineCount,\n        avg_word_length: avgWordLength,\n        token_estimate: tokenEstimate,\n        is_all_alpha: isAllAlpha,\n        is_all_numeric: isAllNumeric,\n        is_all_alphanumeric: isAllAlphanumeric,\n        is_all_ascii: isAllAscii,\n        is_all_lowercase: isAllLowercase,\n        is_all_uppercase: isAllUppercase,\n        has_unicode: !isAllAscii,\n      },\n      null,\n      2\n    )\n  },\n})\n\n/**\n * Operate on text treated as a list of lines.\n *\n * @remarks\n * Operations: `sort`, `sort_desc`, `reverse`, `deduplicate`, `filter_empty`, `trim_each`,\n * `number` (prefix each line with `1.`, `2.`, …), `count`. Sort and deduplicate respect the\n * optional `case_insensitive` flag.\n */\nexport const textLinesTool = new Tool({\n  name: 'text_lines',\n  description:\n    'Perform operations on text treated as a list of lines: sort, deduplicate, reverse, filter empty lines, trim each line, number each line, or count.',\n  inputSchema: validator.object({\n    text: validator.string().required().description('Multi-line text to process'),\n    operation: validator\n      .string()\n      .valid(\n        'sort',\n        'sort_desc',\n        'reverse',\n        'deduplicate',\n        'filter_empty',\n        'trim_each',\n        'number',\n        'count'\n      )\n      .required()\n      .description('Operation to apply to lines'),\n    case_insensitive: validator\n      .boolean()\n      .default(false)\n      .description('For sort / deduplicate: ignore case (default: false)'),\n  }),\n  handler: async (args) => {\n    const {\n      text,\n      operation,\n      case_insensitive: ci,\n    } = args as {\n      text: string\n      operation: string\n      case_insensitive: boolean\n    }\n    const lines = text.split('\\n')\n\n    switch (operation) {\n      case 'sort':\n        return [...lines]\n          .sort((a, b) => (ci ? a.toLowerCase() : a).localeCompare(ci ? b.toLowerCase() : b))\n          .join('\\n')\n      case 'sort_desc':\n        return [...lines]\n          .sort((a, b) => (ci ? b.toLowerCase() : b).localeCompare(ci ? a.toLowerCase() : a))\n          .join('\\n')\n      case 'reverse':\n        return [...lines].reverse().join('\\n')\n      case 'deduplicate': {\n        const seen = new Set<string>()\n        return lines\n          .filter((line) => {\n            const key = ci ? line.toLowerCase() : line\n            if (seen.has(key)) return false\n            seen.add(key)\n            return true\n          })\n          .join('\\n')\n      }\n      case 'filter_empty':\n        return lines.filter((l) => l.trim() !== '').join('\\n')\n      case 'trim_each':\n        return lines.map((l) => l.trim()).join('\\n')\n      case 'number':\n        return lines.map((l, i) => `${i + 1}. ${l}`).join('\\n')\n      case 'count': {\n        const nonEmpty = lines.filter((l) => l.trim() !== '').length\n        return `${lines.length} lines (${nonEmpty} non-empty, ${lines.length - nonEmpty} empty)`\n      }\n      default:\n        return `Error: Unknown operation \"${operation}\".`\n    }\n  },\n})\n"],"mappings":"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"}

package/batteries/tools/text_analysis.mjs

@@ -0,0 +1,117 @@
+import "../../common-DeZaonK1.mjs";
+import { t as Tool } from "../../tool-D2WB1EA1.mjs";
+import { n as SpooledJsonArtifact } from "../../spooled_markdown_artifact-BpUJol0W.mjs";
+import { validator } from "@nhtio/validation";
+//#region src/batteries/tools/text_analysis/index.ts
+/**
+* Pre-constructed tools for extracting counts, token estimates, and character statistics from text.
+*
+* @module @nhtio/adk/batteries/tools/text_analysis
+*
+* @remarks
+* Pre-constructed bundled tools for the `text_analysis` category. Import individually, the whole
+* category, or import every tool via `@nhtio/adk/batteries`.
+*/
+/**
+* Analyze text and return statistics as a JSON document.
+*
+* @remarks
+* Reports character counts (with and without spaces), word/sentence/paragraph/line counts,
+* unique word count, average word length, a rough token estimate (4 chars/token), and a set
+* of character-class booleans (`is_all_alpha`, `is_all_ascii`, etc.).
+*
+* Output is JSON, so the artifact constructor is set to {@link @nhtio/adk!SpooledJsonArtifact} — consumer
+* code can read the result back as a parsed record without re-parsing.
+*/
+var textAnalyzeTool = new Tool({
+	name: "text_analyze",
+	description: "Analyze text and return statistics: character counts, word/sentence/paragraph/line counts, unique word count, average word length, token estimate, and character-set properties.",
+	inputSchema: validator.object({ text: validator.string().required().description("The text to analyze") }),
+	artifactConstructor: () => SpooledJsonArtifact,
+	handler: async (args) => {
+		const { text } = args;
+		const charCount = text.length;
+		const charCountNoSpaces = text.replace(/\s/g, "").length;
+		const words = text.trim() === "" ? [] : text.trim().split(/\s+/);
+		const wordCount = words.length;
+		const sentenceMatches = text.match(/[.!?]+(?:\s|$)/g);
+		const sentenceCount = sentenceMatches ? sentenceMatches.length : text.trim().length > 0 ? 1 : 0;
+		const paragraphCount = text.split(/\n[ \t]*\n/).filter((p) => p.trim().length > 0).length || (text.trim().length > 0 ? 1 : 0);
+		const lineCount = text === "" ? 0 : text.split("\n").length;
+		const tokenEstimate = Math.ceil(text.length / 4);
+		const uniqueWordCount = new Set(words.map((w) => w.toLowerCase().replace(/[^a-z0-9]/g, "")).filter(Boolean)).size;
+		const totalWordLen = words.reduce((sum, w) => sum + w.length, 0);
+		const avgWordLength = wordCount > 0 ? Number.parseFloat((totalWordLen / wordCount).toFixed(2)) : 0;
+		const isAllAlpha = text.trim().length > 0 && /^[a-zA-Z\s]*$/.test(text);
+		const isAllNumeric = /^\d+$/.test(text.trim());
+		const isAllAlphanumeric = text.trim().length > 0 && /^[a-zA-Z0-9\s]*$/.test(text);
+		const isAllAscii = [...text].every((c) => c.charCodeAt(0) < 128);
+		const isAllLowercase = text === text.toLowerCase() && /[a-z]/.test(text);
+		const isAllUppercase = text === text.toUpperCase() && /[A-Z]/.test(text);
+		return JSON.stringify({
+			char_count: charCount,
+			char_count_no_spaces: charCountNoSpaces,
+			word_count: wordCount,
+			unique_word_count: uniqueWordCount,
+			sentence_count: sentenceCount,
+			paragraph_count: paragraphCount,
+			line_count: lineCount,
+			avg_word_length: avgWordLength,
+			token_estimate: tokenEstimate,
+			is_all_alpha: isAllAlpha,
+			is_all_numeric: isAllNumeric,
+			is_all_alphanumeric: isAllAlphanumeric,
+			is_all_ascii: isAllAscii,
+			is_all_lowercase: isAllLowercase,
+			is_all_uppercase: isAllUppercase,
+			has_unicode: !isAllAscii
+		}, null, 2);
+	}
+});
+/**
+* Operate on text treated as a list of lines.
+*
+* @remarks
+* Operations: `sort`, `sort_desc`, `reverse`, `deduplicate`, `filter_empty`, `trim_each`,
+* `number` (prefix each line with `1.`, `2.`, …), `count`. Sort and deduplicate respect the
+* optional `case_insensitive` flag.
+*/
+var textLinesTool = new Tool({
+	name: "text_lines",
+	description: "Perform operations on text treated as a list of lines: sort, deduplicate, reverse, filter empty lines, trim each line, number each line, or count.",
+	inputSchema: validator.object({
+		text: validator.string().required().description("Multi-line text to process"),
+		operation: validator.string().valid("sort", "sort_desc", "reverse", "deduplicate", "filter_empty", "trim_each", "number", "count").required().description("Operation to apply to lines"),
+		case_insensitive: validator.boolean().default(false).description("For sort / deduplicate: ignore case (default: false)")
+	}),
+	handler: async (args) => {
+		const { text, operation, case_insensitive: ci } = args;
+		const lines = text.split("\n");
+		switch (operation) {
+			case "sort": return [...lines].sort((a, b) => (ci ? a.toLowerCase() : a).localeCompare(ci ? b.toLowerCase() : b)).join("\n");
+			case "sort_desc": return [...lines].sort((a, b) => (ci ? b.toLowerCase() : b).localeCompare(ci ? a.toLowerCase() : a)).join("\n");
+			case "reverse": return [...lines].reverse().join("\n");
+			case "deduplicate": {
+				const seen = /* @__PURE__ */ new Set();
+				return lines.filter((line) => {
+					const key = ci ? line.toLowerCase() : line;
+					if (seen.has(key)) return false;
+					seen.add(key);
+					return true;
+				}).join("\n");
+			}
+			case "filter_empty": return lines.filter((l) => l.trim() !== "").join("\n");
+			case "trim_each": return lines.map((l) => l.trim()).join("\n");
+			case "number": return lines.map((l, i) => `${i + 1}. ${l}`).join("\n");
+			case "count": {
+				const nonEmpty = lines.filter((l) => l.trim() !== "").length;
+				return `${lines.length} lines (${nonEmpty} non-empty, ${lines.length - nonEmpty} empty)`;
+			}
+			default: return `Error: Unknown operation "${operation}".`;
+		}
+	}
+});
+//#endregion
+export { textAnalyzeTool, textLinesTool };
+
+//# sourceMappingURL=text_analysis.mjs.map

package/batteries/tools/text_analysis.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"text_analysis.mjs","names":[],"sources":["../../../src/batteries/tools/text_analysis/index.ts"],"sourcesContent":["/**\n * Pre-constructed tools for extracting counts, token estimates, and character statistics from text.\n *\n * @module @nhtio/adk/batteries/tools/text_analysis\n *\n * @remarks\n * Pre-constructed bundled tools for the `text_analysis` category. Import individually, the whole\n * category, or import every tool via `@nhtio/adk/batteries`.\n */\n\nimport { validator } from '@nhtio/validation'\nimport { Tool, SpooledJsonArtifact } from '@nhtio/adk/common'\n\n/**\n * Analyze text and return statistics as a JSON document.\n *\n * @remarks\n * Reports character counts (with and without spaces), word/sentence/paragraph/line counts,\n * unique word count, average word length, a rough token estimate (4 chars/token), and a set\n * of character-class booleans (`is_all_alpha`, `is_all_ascii`, etc.).\n *\n * Output is JSON, so the artifact constructor is set to {@link @nhtio/adk!SpooledJsonArtifact} — consumer\n * code can read the result back as a parsed record without re-parsing.\n */\nexport const textAnalyzeTool = new Tool({\n  name: 'text_analyze',\n  description:\n    'Analyze text and return statistics: character counts, word/sentence/paragraph/line counts, unique word count, average word length, token estimate, and character-set properties.',\n  inputSchema: validator.object({\n    text: validator.string().required().description('The text to analyze'),\n  }),\n  artifactConstructor: () => SpooledJsonArtifact,\n  handler: async (args) => {\n    const { text } = args as { text: string }\n\n    const charCount = text.length\n    const charCountNoSpaces = text.replace(/\\s/g, '').length\n\n    const words = text.trim() === '' ? [] : text.trim().split(/\\s+/)\n    const wordCount = words.length\n\n    const sentenceMatches = text.match(/[.!?]+(?:\\s|$)/g)\n    const sentenceCount = sentenceMatches ? sentenceMatches.length : text.trim().length > 0 ? 1 : 0\n\n    const paragraphs = text.split(/\\n[ \\t]*\\n/).filter((p) => p.trim().length > 0)\n    const paragraphCount = paragraphs.length || (text.trim().length > 0 ? 1 : 0)\n\n    const lineCount = text === '' ? 0 : text.split('\\n').length\n\n    const tokenEstimate = Math.ceil(text.length / 4)\n\n    const uniqueWords = new Set(\n      words.map((w) => w.toLowerCase().replace(/[^a-z0-9]/g, '')).filter(Boolean)\n    )\n    const uniqueWordCount = uniqueWords.size\n\n    const totalWordLen = words.reduce((sum, w) => sum + w.length, 0)\n    const avgWordLength =\n      wordCount > 0 ? Number.parseFloat((totalWordLen / wordCount).toFixed(2)) : 0\n\n    const isAllAlpha = text.trim().length > 0 && /^[a-zA-Z\\s]*$/.test(text)\n    const isAllNumeric = /^\\d+$/.test(text.trim())\n    const isAllAlphanumeric = text.trim().length > 0 && /^[a-zA-Z0-9\\s]*$/.test(text)\n    const isAllAscii = [...text].every((c) => c.charCodeAt(0) < 128)\n    const isAllLowercase = text === text.toLowerCase() && /[a-z]/.test(text)\n    const isAllUppercase = text === text.toUpperCase() && /[A-Z]/.test(text)\n\n    return JSON.stringify(\n      {\n        char_count: charCount,\n        char_count_no_spaces: charCountNoSpaces,\n        word_count: wordCount,\n        unique_word_count: uniqueWordCount,\n        sentence_count: sentenceCount,\n        paragraph_count: paragraphCount,\n        line_count: lineCount,\n        avg_word_length: avgWordLength,\n        token_estimate: tokenEstimate,\n        is_all_alpha: isAllAlpha,\n        is_all_numeric: isAllNumeric,\n        is_all_alphanumeric: isAllAlphanumeric,\n        is_all_ascii: isAllAscii,\n        is_all_lowercase: isAllLowercase,\n        is_all_uppercase: isAllUppercase,\n        has_unicode: !isAllAscii,\n      },\n      null,\n      2\n    )\n  },\n})\n\n/**\n * Operate on text treated as a list of lines.\n *\n * @remarks\n * Operations: `sort`, `sort_desc`, `reverse`, `deduplicate`, `filter_empty`, `trim_each`,\n * `number` (prefix each line with `1.`, `2.`, …), `count`. Sort and deduplicate respect the\n * optional `case_insensitive` flag.\n */\nexport const textLinesTool = new Tool({\n  name: 'text_lines',\n  description:\n    'Perform operations on text treated as a list of lines: sort, deduplicate, reverse, filter empty lines, trim each line, number each line, or count.',\n  inputSchema: validator.object({\n    text: validator.string().required().description('Multi-line text to process'),\n    operation: validator\n      .string()\n      .valid(\n        'sort',\n        'sort_desc',\n        'reverse',\n        'deduplicate',\n        'filter_empty',\n        'trim_each',\n        'number',\n        'count'\n      )\n      .required()\n      .description('Operation to apply to lines'),\n    case_insensitive: validator\n      .boolean()\n      .default(false)\n      .description('For sort / deduplicate: ignore case (default: false)'),\n  }),\n  handler: async (args) => {\n    const {\n      text,\n      operation,\n      case_insensitive: ci,\n    } = args as {\n      text: string\n      operation: string\n      case_insensitive: boolean\n    }\n    const lines = text.split('\\n')\n\n    switch (operation) {\n      case 'sort':\n        return [...lines]\n          .sort((a, b) => (ci ? a.toLowerCase() : a).localeCompare(ci ? b.toLowerCase() : b))\n          .join('\\n')\n      case 'sort_desc':\n        return [...lines]\n          .sort((a, b) => (ci ? b.toLowerCase() : b).localeCompare(ci ? a.toLowerCase() : a))\n          .join('\\n')\n      case 'reverse':\n        return [...lines].reverse().join('\\n')\n      case 'deduplicate': {\n        const seen = new Set<string>()\n        return lines\n          .filter((line) => {\n            const key = ci ? line.toLowerCase() : line\n            if (seen.has(key)) return false\n            seen.add(key)\n            return true\n          })\n          .join('\\n')\n      }\n      case 'filter_empty':\n        return lines.filter((l) => l.trim() !== '').join('\\n')\n      case 'trim_each':\n        return lines.map((l) => l.trim()).join('\\n')\n      case 'number':\n        return lines.map((l, i) => `${i + 1}. ${l}`).join('\\n')\n      case 'count': {\n        const nonEmpty = lines.filter((l) => l.trim() !== '').length\n        return `${lines.length} lines (${nonEmpty} non-empty, ${lines.length - nonEmpty} empty)`\n      }\n      default:\n        return `Error: Unknown operation \"${operation}\".`\n    }\n  },\n})\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;AAwBA,IAAa,kBAAkB,IAAI,KAAK;CACtC,MAAM;CACN,aACE;CACF,aAAa,UAAU,OAAO,EAC5B,MAAM,UAAU,OAAO,EAAE,SAAS,EAAE,YAAY,qBAAqB,EACvE,CAAC;CACD,2BAA2B;CAC3B,SAAS,OAAO,SAAS;EACvB,MAAM,EAAE,SAAS;EAEjB,MAAM,YAAY,KAAK;EACvB,MAAM,oBAAoB,KAAK,QAAQ,OAAO,EAAE,EAAE;EAElD,MAAM,QAAQ,KAAK,KAAK,MAAM,KAAK,CAAC,IAAI,KAAK,KAAK,EAAE,MAAM,KAAK;EAC/D,MAAM,YAAY,MAAM;EAExB,MAAM,kBAAkB,KAAK,MAAM,iBAAiB;EACpD,MAAM,gBAAgB,kBAAkB,gBAAgB,SAAS,KAAK,KAAK,EAAE,SAAS,IAAI,IAAI;EAG9F,MAAM,iBADa,KAAK,MAAM,YAAY,EAAE,QAAQ,MAAM,EAAE,KAAK,EAAE,SAAS,CACrD,EAAW,WAAW,KAAK,KAAK,EAAE,SAAS,IAAI,IAAI;EAE1E,MAAM,YAAY,SAAS,KAAK,IAAI,KAAK,MAAM,IAAI,EAAE;EAErD,MAAM,gBAAgB,KAAK,KAAK,KAAK,SAAS,CAAC;EAK/C,MAAM,kBAAkB,IAHA,IACtB,MAAM,KAAK,MAAM,EAAE,YAAY,EAAE,QAAQ,cAAc,EAAE,CAAC,EAAE,OAAO,OAAO,CAEpD,EAAY;EAEpC,MAAM,eAAe,MAAM,QAAQ,KAAK,MAAM,MAAM,EAAE,QAAQ,CAAC;EAC/D,MAAM,gBACJ,YAAY,IAAI,OAAO,YAAY,eAAe,WAAW,QAAQ,CAAC,CAAC,IAAI;EAE7E,MAAM,aAAa,KAAK,KAAK,EAAE,SAAS,KAAK,gBAAgB,KAAK,IAAI;EACtE,MAAM,eAAe,QAAQ,KAAK,KAAK,KAAK,CAAC;EAC7C,MAAM,oBAAoB,KAAK,KAAK,EAAE,SAAS,KAAK,mBAAmB,KAAK,IAAI;EAChF,MAAM,aAAa,CAAC,GAAG,IAAI,EAAE,OAAO,MAAM,EAAE,WAAW,CAAC,IAAI,GAAG;EAC/D,MAAM,iBAAiB,SAAS,KAAK,YAAY,KAAK,QAAQ,KAAK,IAAI;EACvE,MAAM,iBAAiB,SAAS,KAAK,YAAY,KAAK,QAAQ,KAAK,IAAI;EAEvE,OAAO,KAAK,UACV;GACE,YAAY;GACZ,sBAAsB;GACtB,YAAY;GACZ,mBAAmB;GACnB,gBAAgB;GAChB,iBAAiB;GACjB,YAAY;GACZ,iBAAiB;GACjB,gBAAgB;GAChB,cAAc;GACd,gBAAgB;GAChB,qBAAqB;GACrB,cAAc;GACd,kBAAkB;GAClB,kBAAkB;GAClB,aAAa,CAAC;EAChB,GACA,MACA,CACF;CACF;AACF,CAAC;;;;;;;;;AAUD,IAAa,gBAAgB,IAAI,KAAK;CACpC,MAAM;CACN,aACE;CACF,aAAa,UAAU,OAAO;EAC5B,MAAM,UAAU,OAAO,EAAE,SAAS,EAAE,YAAY,4BAA4B;EAC5E,WAAW,UACR,OAAO,EACP,MACC,QACA,aACA,WACA,eACA,gBACA,aACA,UACA,OACF,EACC,SAAS,EACT,YAAY,6BAA6B;EAC5C,kBAAkB,UACf,QAAQ,EACR,QAAQ,KAAK,EACb,YAAY,sDAAsD;CACvE,CAAC;CACD,SAAS,OAAO,SAAS;EACvB,MAAM,EACJ,MACA,WACA,kBAAkB,OAChB;EAKJ,MAAM,QAAQ,KAAK,MAAM,IAAI;EAE7B,QAAQ,WAAR;GACE,KAAK,QACH,OAAO,CAAC,GAAG,KAAK,EACb,MAAM,GAAG,OAAO,KAAK,EAAE,YAAY,IAAI,GAAG,cAAc,KAAK,EAAE,YAAY,IAAI,CAAC,CAAC,EACjF,KAAK,IAAI;GACd,KAAK,aACH,OAAO,CAAC,GAAG,KAAK,EACb,MAAM,GAAG,OAAO,KAAK,EAAE,YAAY,IAAI,GAAG,cAAc,KAAK,EAAE,YAAY,IAAI,CAAC,CAAC,EACjF,KAAK,IAAI;GACd,KAAK,WACH,OAAO,CAAC,GAAG,KAAK,EAAE,QAAQ,EAAE,KAAK,IAAI;GACvC,KAAK,eAAe;IAClB,MAAM,uBAAO,IAAI,IAAY;IAC7B,OAAO,MACJ,QAAQ,SAAS;KAChB,MAAM,MAAM,KAAK,KAAK,YAAY,IAAI;KACtC,IAAI,KAAK,IAAI,GAAG,GAAG,OAAO;KAC1B,KAAK,IAAI,GAAG;KACZ,OAAO;IACT,CAAC,EACA,KAAK,IAAI;GACd;GACA,KAAK,gBACH,OAAO,MAAM,QAAQ,MAAM,EAAE,KAAK,MAAM,EAAE,EAAE,KAAK,IAAI;GACvD,KAAK,aACH,OAAO,MAAM,KAAK,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK,IAAI;GAC7C,KAAK,UACH,OAAO,MAAM,KAAK,GAAG,MAAM,GAAG,IAAI,EAAE,IAAI,GAAG,EAAE,KAAK,IAAI;GACxD,KAAK,SAAS;IACZ,MAAM,WAAW,MAAM,QAAQ,MAAM,EAAE,KAAK,MAAM,EAAE,EAAE;IACtD,OAAO,GAAG,MAAM,OAAO,UAAU,SAAS,cAAc,MAAM,SAAS,SAAS;GAClF;GACA,SACE,OAAO,6BAA6B,UAAU;EAClD;CACF;AACF,CAAC"}

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

@@ -0,0 +1,28 @@
+/**
+ * Pre-constructed tools for text diffs, similarity checks, and edit-distance comparisons.
+ *
+ * @module @nhtio/adk/batteries/tools/text_comparison
+ *
+ * @remarks
+ * Pre-constructed bundled tools for the `text_comparison` category. Import individually, the whole
+ * category, or import every tool via `@nhtio/adk/batteries`.
+ */
+import { Tool } from "../../../common";
+/**
+ * Compare two texts and emit a unified-style diff plus an additions/removals summary.
+ *
+ * @remarks
+ * `mode: 'lines'` (default) compares line-by-line; `mode: 'words'` compares word-by-word. The
+ * output is clipped at 60 diff lines — the suffix `… (N more lines truncated)` is appended if
+ * the diff is larger. Identical inputs short-circuit with `Texts are identical`.
+ */
+export declare const textDiffTool: Tool<import("../../../common").SpooledArtifact>;
+/**
+ * Report the Levenshtein edit distance and a similarity percentage between two strings.
+ *
+ * @remarks
+ * Useful for fuzzy matching. The percentage is `(1 - distance / max(len_a, len_b)) * 100`, with
+ * a human-readable label appended (`identical` / `very similar` / `similar` / `somewhat
+ * similar` / `different` / `very different`).
+ */
+export declare const stringSimilarityTool: Tool<import("../../../common").SpooledArtifact>;

package/batteries/tools/text_comparison.cjs

@@ -0,0 +1,96 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+require("../../chunk-KmRHZBOW.js");
+require("../../common-Od8edUXU.js");
+const require_tool = require("../../tool-COSeH8I6.js");
+let _nhtio_validation = require("@nhtio/validation");
+let diff = require("diff");
+let fastest_levenshtein = require("fastest-levenshtein");
+//#region src/batteries/tools/text_comparison/index.ts
+/**
+* Pre-constructed tools for text diffs, similarity checks, and edit-distance comparisons.
+*
+* @module @nhtio/adk/batteries/tools/text_comparison
+*
+* @remarks
+* Pre-constructed bundled tools for the `text_comparison` category. Import individually, the whole
+* category, or import every tool via `@nhtio/adk/batteries`.
+*/
+/**
+* Compare two texts and emit a unified-style diff plus an additions/removals summary.
+*
+* @remarks
+* `mode: 'lines'` (default) compares line-by-line; `mode: 'words'` compares word-by-word. The
+* output is clipped at 60 diff lines — the suffix `… (N more lines truncated)` is appended if
+* the diff is larger. Identical inputs short-circuit with `Texts are identical`.
+*/
+var textDiffTool = new require_tool.Tool({
+	name: "text_diff",
+	description: "Compare two texts and show what changed. Returns a summary of additions, deletions, and a unified-style diff.",
+	inputSchema: _nhtio_validation.validator.object({
+		text_a: _nhtio_validation.validator.string().required().allow("").description("Original text (before)"),
+		text_b: _nhtio_validation.validator.string().required().allow("").description("New text (after)"),
+		mode: _nhtio_validation.validator.string().valid("lines", "words").default("lines").description("Compare line-by-line or word-by-word (default: lines)")
+	}),
+	handler: async (args) => {
+		const { text_a: a, text_b: b, mode } = args;
+		if (a === b) return "Texts are identical — no differences found.";
+		const changes = mode === "words" ? (0, diff.diffWords)(a, b) : (0, diff.diffLines)(a, b);
+		let added = 0;
+		let removed = 0;
+		let unchanged = 0;
+		const diffOutput = [];
+		for (const part of changes) {
+			const unit = mode === "words" ? (part.value.match(/\S+/g) ?? []).length : part.count ?? 1;
+			if (part.added) {
+				added += unit;
+				for (const line of part.value.split("\n").filter((l) => l !== "" || mode === "words")) if (line !== "") diffOutput.push(`+ ${line}`);
+			} else if (part.removed) {
+				removed += unit;
+				for (const line of part.value.split("\n").filter((l) => l !== "" || mode === "words")) if (line !== "") diffOutput.push(`- ${line}`);
+			} else unchanged += unit;
+		}
+		const unit = mode === "lines" ? "line" : "word";
+		const summary = `+${added} ${unit}${added !== 1 ? "s" : ""} added, -${removed} ${unit}${removed !== 1 ? "s" : ""} removed, ${unchanged} unchanged`;
+		const MAX_DIFF_LINES = 60;
+		const truncated = diffOutput.length > MAX_DIFF_LINES ? `\n… (${diffOutput.length - MAX_DIFF_LINES} more lines truncated)` : "";
+		return [
+			summary,
+			"",
+			...diffOutput.slice(0, MAX_DIFF_LINES)
+		].join("\n") + truncated;
+	}
+});
+/**
+* Report the Levenshtein edit distance and a similarity percentage between two strings.
+*
+* @remarks
+* Useful for fuzzy matching. The percentage is `(1 - distance / max(len_a, len_b)) * 100`, with
+* a human-readable label appended (`identical` / `very similar` / `similar` / `somewhat
+* similar` / `different` / `very different`).
+*/
+var stringSimilarityTool = new require_tool.Tool({
+	name: "string_similarity",
+	description: "Calculate edit distance and similarity percentage between two strings using Levenshtein distance. Useful for fuzzy matching.",
+	inputSchema: _nhtio_validation.validator.object({
+		a: _nhtio_validation.validator.string().required().allow("").description("First string"),
+		b: _nhtio_validation.validator.string().required().allow("").description("Second string"),
+		case_insensitive: _nhtio_validation.validator.boolean().default(false).description("Ignore case when comparing (default: false)")
+	}),
+	handler: async (args) => {
+		let { a, b } = args;
+		const { case_insensitive: ci } = args;
+		if (ci) {
+			a = a.toLowerCase();
+			b = b.toLowerCase();
+		}
+		const dist = (0, fastest_levenshtein.distance)(a, b);
+		const maxLen = Math.max(a.length, b.length);
+		const pct = maxLen === 0 ? 100 : Number.parseFloat(((1 - dist / maxLen) * 100).toFixed(1));
+		return `Edit distance: ${dist}\nSimilarity: ${pct}% (${pct === 100 ? "identical" : pct >= 90 ? "very similar" : pct >= 70 ? "similar" : pct >= 50 ? "somewhat similar" : pct >= 30 ? "different" : "very different"})`;
+	}
+});
+//#endregion
+exports.stringSimilarityTool = stringSimilarityTool;
+exports.textDiffTool = textDiffTool;
+
+//# sourceMappingURL=text_comparison.cjs.map