@nhtio/adk 0.1.0-master-f0aa531d

package/batteries/tools/memory.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.cjs","names":[],"sources":["../../../src/batteries/tools/memory/index.ts"],"sourcesContent":["/**\n * Pre-constructed CRUD tools for model-visible ADK memory management.\n *\n * @module @nhtio/adk/batteries/tools/memory\n *\n * @remarks\n * Pre-constructed CRUD tools that expose the ADK's {@link @nhtio/adk!Memory} surface to the model.\n * Each tool delegates to the corresponding callback on the active {@link @nhtio/adk!DispatchContext}\n * (`fetchMemories`, `storeMemory`, `mutateMemory`, `deleteMemory`) — the persistence layer is\n * whatever the consumer wired into the runner.\n *\n * Memory entries carry agent-internal `confidence` / `importance` scores and are rendered\n * through the LLM battery's recall-tier envelope. Letting the model author and curate its own\n * memories is the canonical use case for these tools; deployers who do not want the model to\n * mutate memory should simply not register the relevant tools.\n *\n * Output is JSON for every tool so consumers can parse the result without re-tokenising — the\n * artifact constructor is set to {@link @nhtio/adk!SpooledJsonArtifact}.\n *\n * Tools:\n * - {@link listMemoriesTool} — read-only list of every memory currently held by the context.\n * - {@link storeMemoryTool} — create a new memory (auto-generates `id` / `createdAt` /\n *   `updatedAt` unless explicit values are supplied).\n * - {@link updateMemoryTool} — replace an existing memory by `id`. Bumps `updatedAt`.\n * - {@link deleteMemoryTool} — remove a memory by `id`.\n */\n\nimport { DateTime } from 'luxon'\nimport { v6 as uuidv6 } from 'uuid'\nimport { isError } from '@nhtio/adk/guards'\nimport { validator } from '@nhtio/validation'\nimport { Memory, SpooledJsonArtifact, Tool } from '@nhtio/adk/common'\n\nconst serialiseMemory = (m: Memory): Record<string, unknown> => ({\n  id: m.id,\n  content: m.content.toString(),\n  confidence: m.confidence,\n  importance: m.importance,\n  createdAt: m.createdAt.toISO(),\n  updatedAt: m.updatedAt.toISO(),\n})\n\n/**\n * List every memory currently held by the active execution context.\n *\n * @remarks\n * Delegates to `ctx.fetchMemories()`. Returns a JSON-encoded array of memory records (id,\n * content, confidence, importance, createdAt, updatedAt). The model can use the `id` values\n * to drive subsequent `update_memory` / `delete_memory` calls.\n */\nexport const listMemoriesTool = new Tool({\n  name: 'list_memories',\n  description:\n    'List every memory currently held by the agent. Returns a JSON array of memory records with id, content, confidence, importance, createdAt, and updatedAt.',\n  inputSchema: validator.object({}),\n  artifactConstructor: () => SpooledJsonArtifact,\n  handler: async (_args, ctx) => {\n    try {\n      const memories = await ctx.fetchMemories()\n      return JSON.stringify(memories.map(serialiseMemory), null, 2)\n    } catch (err) {\n      return `Error: ${isError(err) ? err.message : String(err)}`\n    }\n  },\n})\n\n/**\n * Create a new {@link @nhtio/adk!Memory} record and persist it via the context's `storeMemory` callback.\n *\n * @remarks\n * When `id` is omitted, a UUID v6 is generated. When `createdAt` / `updatedAt` are omitted,\n * the current time is used. The model authors `content`, `confidence`, and `importance`\n * directly. The resulting record is added to `ctx.turnMemories` and flushed to the consumer's\n * persistence layer.\n */\nexport const storeMemoryTool = new Tool({\n  name: 'store_memory',\n  description:\n    'Store a new memory record. Provide the content, your confidence (0–1) that the memory is accurate, and the importance (0–1) of the memory for future recall. id and timestamps are auto-generated if omitted.',\n  inputSchema: validator.object({\n    content: validator.string().required().description('The memory content as a plain string.'),\n    confidence: validator\n      .number()\n      .min(0)\n      .max(1)\n      .required()\n      .description('Confidence in [0, 1] that this memory is accurate.'),\n    importance: validator\n      .number()\n      .min(0)\n      .max(1)\n      .required()\n      .description('Importance in [0, 1] — how much weight the memory should carry on recall.'),\n    id: validator\n      .string()\n      .optional()\n      .description('Optional stable id. Auto-generated when absent.'),\n  }),\n  artifactConstructor: () => SpooledJsonArtifact,\n  handler: async (args, ctx) => {\n    const { content, confidence, importance, id } = args as {\n      content: string\n      confidence: number\n      importance: number\n      id?: string\n    }\n    try {\n      const now = DateTime.now()\n      const memory = new Memory({\n        id: id ?? uuidv6(),\n        content,\n        confidence,\n        importance,\n        createdAt: now,\n        updatedAt: now,\n      })\n      await ctx.storeMemory(memory)\n      return JSON.stringify({ ok: true, memory: serialiseMemory(memory) }, null, 2)\n    } catch (err) {\n      return `Error: ${isError(err) ? err.message : String(err)}`\n    }\n  },\n})\n\n/**\n * Replace an existing {@link @nhtio/adk!Memory} by `id`.\n *\n * @remarks\n * The model supplies `id` plus any subset of `content` / `confidence` / `importance`; fields\n * left undefined retain their prior values. `updatedAt` is always bumped to the current time;\n * `createdAt` is preserved. Returns an error when no memory with the supplied `id` is found.\n */\nexport const updateMemoryTool = new Tool({\n  name: 'update_memory',\n  description:\n    'Update an existing memory by id. Supply any subset of content / confidence / importance — omitted fields retain their prior values. updatedAt is always refreshed.',\n  inputSchema: validator.object({\n    id: validator.string().required().description('Id of the memory to update.'),\n    content: validator.string().optional().description('Replacement content.'),\n    confidence: validator\n      .number()\n      .min(0)\n      .max(1)\n      .optional()\n      .description('Replacement confidence in [0, 1].'),\n    importance: validator\n      .number()\n      .min(0)\n      .max(1)\n      .optional()\n      .description('Replacement importance in [0, 1].'),\n  }),\n  artifactConstructor: () => SpooledJsonArtifact,\n  handler: async (args, ctx) => {\n    const { id, content, confidence, importance } = args as {\n      id: string\n      content?: string\n      confidence?: number\n      importance?: number\n    }\n    try {\n      const memories = await ctx.fetchMemories()\n      const existing = memories.find((m) => m.id === id)\n      if (!existing) {\n        return `Error: No memory found with id \"${id}\".`\n      }\n      const updated = new Memory({\n        id: existing.id,\n        content: content ?? existing.content,\n        confidence: confidence ?? existing.confidence,\n        importance: importance ?? existing.importance,\n        createdAt: existing.createdAt,\n        updatedAt: DateTime.now(),\n      })\n      await ctx.mutateMemory(updated)\n      return JSON.stringify({ ok: true, memory: serialiseMemory(updated) }, null, 2)\n    } catch (err) {\n      return `Error: ${isError(err) ? err.message : String(err)}`\n    }\n  },\n})\n\n/**\n * Remove an existing {@link @nhtio/adk!Memory} by `id`.\n *\n * @remarks\n * Delegates to `ctx.deleteMemory(id)`. Returns `{ ok: true, id }` on success regardless of\n * whether a memory was actually present — `deleteMemory` is idempotent at the ADK level.\n */\nexport const deleteMemoryTool = new Tool({\n  name: 'delete_memory',\n  description: 'Delete a memory by id.',\n  inputSchema: validator.object({\n    id: validator.string().required().description('Id of the memory to delete.'),\n  }),\n  artifactConstructor: () => SpooledJsonArtifact,\n  handler: async (args, ctx) => {\n    const { id } = args as { id: string }\n    try {\n      await ctx.deleteMemory(id)\n      return JSON.stringify({ ok: true, id }, null, 2)\n    } catch (err) {\n      return `Error: ${isError(err) ? err.message : String(err)}`\n    }\n  },\n})\n\n/**\n * Convenience tuple of every memory CRUD tool. Spread into a {@link @nhtio/adk!ToolRegistry} to register\n * the entire category at once: `registry.register(...memoryTools)`.\n */\nexport const memoryTools = [\n  listMemoriesTool,\n  storeMemoryTool,\n  updateMemoryTool,\n  deleteMemoryTool,\n] as const\n"],"mappings":"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"}

package/batteries/tools/memory.mjs

@@ -0,0 +1,187 @@
+import { o as isError } from "../../tool_registry-DqLOyGyG.mjs";
+import { r as Memory } from "../../thought-CDb457b4.mjs";
+import "../../common-DeZaonK1.mjs";
+import { t as Tool } from "../../tool-D2WB1EA1.mjs";
+import { n as SpooledJsonArtifact } from "../../spooled_markdown_artifact-BpUJol0W.mjs";
+import "../../guards.mjs";
+import { validator } from "@nhtio/validation";
+import { v6 } from "uuid";
+import { DateTime } from "luxon";
+//#region src/batteries/tools/memory/index.ts
+/**
+* Pre-constructed CRUD tools for model-visible ADK memory management.
+*
+* @module @nhtio/adk/batteries/tools/memory
+*
+* @remarks
+* Pre-constructed CRUD tools that expose the ADK's {@link @nhtio/adk!Memory} surface to the model.
+* Each tool delegates to the corresponding callback on the active {@link @nhtio/adk!DispatchContext}
+* (`fetchMemories`, `storeMemory`, `mutateMemory`, `deleteMemory`) — the persistence layer is
+* whatever the consumer wired into the runner.
+*
+* Memory entries carry agent-internal `confidence` / `importance` scores and are rendered
+* through the LLM battery's recall-tier envelope. Letting the model author and curate its own
+* memories is the canonical use case for these tools; deployers who do not want the model to
+* mutate memory should simply not register the relevant tools.
+*
+* Output is JSON for every tool so consumers can parse the result without re-tokenising — the
+* artifact constructor is set to {@link @nhtio/adk!SpooledJsonArtifact}.
+*
+* Tools:
+* - {@link listMemoriesTool} — read-only list of every memory currently held by the context.
+* - {@link storeMemoryTool} — create a new memory (auto-generates `id` / `createdAt` /
+*   `updatedAt` unless explicit values are supplied).
+* - {@link updateMemoryTool} — replace an existing memory by `id`. Bumps `updatedAt`.
+* - {@link deleteMemoryTool} — remove a memory by `id`.
+*/
+var serialiseMemory = (m) => ({
+	id: m.id,
+	content: m.content.toString(),
+	confidence: m.confidence,
+	importance: m.importance,
+	createdAt: m.createdAt.toISO(),
+	updatedAt: m.updatedAt.toISO()
+});
+/**
+* List every memory currently held by the active execution context.
+*
+* @remarks
+* Delegates to `ctx.fetchMemories()`. Returns a JSON-encoded array of memory records (id,
+* content, confidence, importance, createdAt, updatedAt). The model can use the `id` values
+* to drive subsequent `update_memory` / `delete_memory` calls.
+*/
+var listMemoriesTool = new Tool({
+	name: "list_memories",
+	description: "List every memory currently held by the agent. Returns a JSON array of memory records with id, content, confidence, importance, createdAt, and updatedAt.",
+	inputSchema: validator.object({}),
+	artifactConstructor: () => SpooledJsonArtifact,
+	handler: async (_args, ctx) => {
+		try {
+			const memories = await ctx.fetchMemories();
+			return JSON.stringify(memories.map(serialiseMemory), null, 2);
+		} catch (err) {
+			return `Error: ${isError(err) ? err.message : String(err)}`;
+		}
+	}
+});
+/**
+* Create a new {@link @nhtio/adk!Memory} record and persist it via the context's `storeMemory` callback.
+*
+* @remarks
+* When `id` is omitted, a UUID v6 is generated. When `createdAt` / `updatedAt` are omitted,
+* the current time is used. The model authors `content`, `confidence`, and `importance`
+* directly. The resulting record is added to `ctx.turnMemories` and flushed to the consumer's
+* persistence layer.
+*/
+var storeMemoryTool = new Tool({
+	name: "store_memory",
+	description: "Store a new memory record. Provide the content, your confidence (0–1) that the memory is accurate, and the importance (0–1) of the memory for future recall. id and timestamps are auto-generated if omitted.",
+	inputSchema: validator.object({
+		content: validator.string().required().description("The memory content as a plain string."),
+		confidence: validator.number().min(0).max(1).required().description("Confidence in [0, 1] that this memory is accurate."),
+		importance: validator.number().min(0).max(1).required().description("Importance in [0, 1] — how much weight the memory should carry on recall."),
+		id: validator.string().optional().description("Optional stable id. Auto-generated when absent.")
+	}),
+	artifactConstructor: () => SpooledJsonArtifact,
+	handler: async (args, ctx) => {
+		const { content, confidence, importance, id } = args;
+		try {
+			const now = DateTime.now();
+			const memory = new Memory({
+				id: id ?? v6(),
+				content,
+				confidence,
+				importance,
+				createdAt: now,
+				updatedAt: now
+			});
+			await ctx.storeMemory(memory);
+			return JSON.stringify({
+				ok: true,
+				memory: serialiseMemory(memory)
+			}, null, 2);
+		} catch (err) {
+			return `Error: ${isError(err) ? err.message : String(err)}`;
+		}
+	}
+});
+/**
+* Replace an existing {@link @nhtio/adk!Memory} by `id`.
+*
+* @remarks
+* The model supplies `id` plus any subset of `content` / `confidence` / `importance`; fields
+* left undefined retain their prior values. `updatedAt` is always bumped to the current time;
+* `createdAt` is preserved. Returns an error when no memory with the supplied `id` is found.
+*/
+var updateMemoryTool = new Tool({
+	name: "update_memory",
+	description: "Update an existing memory by id. Supply any subset of content / confidence / importance — omitted fields retain their prior values. updatedAt is always refreshed.",
+	inputSchema: validator.object({
+		id: validator.string().required().description("Id of the memory to update."),
+		content: validator.string().optional().description("Replacement content."),
+		confidence: validator.number().min(0).max(1).optional().description("Replacement confidence in [0, 1]."),
+		importance: validator.number().min(0).max(1).optional().description("Replacement importance in [0, 1].")
+	}),
+	artifactConstructor: () => SpooledJsonArtifact,
+	handler: async (args, ctx) => {
+		const { id, content, confidence, importance } = args;
+		try {
+			const existing = (await ctx.fetchMemories()).find((m) => m.id === id);
+			if (!existing) return `Error: No memory found with id "${id}".`;
+			const updated = new Memory({
+				id: existing.id,
+				content: content ?? existing.content,
+				confidence: confidence ?? existing.confidence,
+				importance: importance ?? existing.importance,
+				createdAt: existing.createdAt,
+				updatedAt: DateTime.now()
+			});
+			await ctx.mutateMemory(updated);
+			return JSON.stringify({
+				ok: true,
+				memory: serialiseMemory(updated)
+			}, null, 2);
+		} catch (err) {
+			return `Error: ${isError(err) ? err.message : String(err)}`;
+		}
+	}
+});
+/**
+* Remove an existing {@link @nhtio/adk!Memory} by `id`.
+*
+* @remarks
+* Delegates to `ctx.deleteMemory(id)`. Returns `{ ok: true, id }` on success regardless of
+* whether a memory was actually present — `deleteMemory` is idempotent at the ADK level.
+*/
+var deleteMemoryTool = new Tool({
+	name: "delete_memory",
+	description: "Delete a memory by id.",
+	inputSchema: validator.object({ id: validator.string().required().description("Id of the memory to delete.") }),
+	artifactConstructor: () => SpooledJsonArtifact,
+	handler: async (args, ctx) => {
+		const { id } = args;
+		try {
+			await ctx.deleteMemory(id);
+			return JSON.stringify({
+				ok: true,
+				id
+			}, null, 2);
+		} catch (err) {
+			return `Error: ${isError(err) ? err.message : String(err)}`;
+		}
+	}
+});
+/**
+* Convenience tuple of every memory CRUD tool. Spread into a {@link @nhtio/adk!ToolRegistry} to register
+* the entire category at once: `registry.register(...memoryTools)`.
+*/
+var memoryTools = [
+	listMemoriesTool,
+	storeMemoryTool,
+	updateMemoryTool,
+	deleteMemoryTool
+];
+//#endregion
+export { deleteMemoryTool, listMemoriesTool, memoryTools, storeMemoryTool, updateMemoryTool };
+
+//# sourceMappingURL=memory.mjs.map

package/batteries/tools/memory.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.mjs","names":[],"sources":["../../../src/batteries/tools/memory/index.ts"],"sourcesContent":["/**\n * Pre-constructed CRUD tools for model-visible ADK memory management.\n *\n * @module @nhtio/adk/batteries/tools/memory\n *\n * @remarks\n * Pre-constructed CRUD tools that expose the ADK's {@link @nhtio/adk!Memory} surface to the model.\n * Each tool delegates to the corresponding callback on the active {@link @nhtio/adk!DispatchContext}\n * (`fetchMemories`, `storeMemory`, `mutateMemory`, `deleteMemory`) — the persistence layer is\n * whatever the consumer wired into the runner.\n *\n * Memory entries carry agent-internal `confidence` / `importance` scores and are rendered\n * through the LLM battery's recall-tier envelope. Letting the model author and curate its own\n * memories is the canonical use case for these tools; deployers who do not want the model to\n * mutate memory should simply not register the relevant tools.\n *\n * Output is JSON for every tool so consumers can parse the result without re-tokenising — the\n * artifact constructor is set to {@link @nhtio/adk!SpooledJsonArtifact}.\n *\n * Tools:\n * - {@link listMemoriesTool} — read-only list of every memory currently held by the context.\n * - {@link storeMemoryTool} — create a new memory (auto-generates `id` / `createdAt` /\n *   `updatedAt` unless explicit values are supplied).\n * - {@link updateMemoryTool} — replace an existing memory by `id`. Bumps `updatedAt`.\n * - {@link deleteMemoryTool} — remove a memory by `id`.\n */\n\nimport { DateTime } from 'luxon'\nimport { v6 as uuidv6 } from 'uuid'\nimport { isError } from '@nhtio/adk/guards'\nimport { validator } from '@nhtio/validation'\nimport { Memory, SpooledJsonArtifact, Tool } from '@nhtio/adk/common'\n\nconst serialiseMemory = (m: Memory): Record<string, unknown> => ({\n  id: m.id,\n  content: m.content.toString(),\n  confidence: m.confidence,\n  importance: m.importance,\n  createdAt: m.createdAt.toISO(),\n  updatedAt: m.updatedAt.toISO(),\n})\n\n/**\n * List every memory currently held by the active execution context.\n *\n * @remarks\n * Delegates to `ctx.fetchMemories()`. Returns a JSON-encoded array of memory records (id,\n * content, confidence, importance, createdAt, updatedAt). The model can use the `id` values\n * to drive subsequent `update_memory` / `delete_memory` calls.\n */\nexport const listMemoriesTool = new Tool({\n  name: 'list_memories',\n  description:\n    'List every memory currently held by the agent. Returns a JSON array of memory records with id, content, confidence, importance, createdAt, and updatedAt.',\n  inputSchema: validator.object({}),\n  artifactConstructor: () => SpooledJsonArtifact,\n  handler: async (_args, ctx) => {\n    try {\n      const memories = await ctx.fetchMemories()\n      return JSON.stringify(memories.map(serialiseMemory), null, 2)\n    } catch (err) {\n      return `Error: ${isError(err) ? err.message : String(err)}`\n    }\n  },\n})\n\n/**\n * Create a new {@link @nhtio/adk!Memory} record and persist it via the context's `storeMemory` callback.\n *\n * @remarks\n * When `id` is omitted, a UUID v6 is generated. When `createdAt` / `updatedAt` are omitted,\n * the current time is used. The model authors `content`, `confidence`, and `importance`\n * directly. The resulting record is added to `ctx.turnMemories` and flushed to the consumer's\n * persistence layer.\n */\nexport const storeMemoryTool = new Tool({\n  name: 'store_memory',\n  description:\n    'Store a new memory record. Provide the content, your confidence (0–1) that the memory is accurate, and the importance (0–1) of the memory for future recall. id and timestamps are auto-generated if omitted.',\n  inputSchema: validator.object({\n    content: validator.string().required().description('The memory content as a plain string.'),\n    confidence: validator\n      .number()\n      .min(0)\n      .max(1)\n      .required()\n      .description('Confidence in [0, 1] that this memory is accurate.'),\n    importance: validator\n      .number()\n      .min(0)\n      .max(1)\n      .required()\n      .description('Importance in [0, 1] — how much weight the memory should carry on recall.'),\n    id: validator\n      .string()\n      .optional()\n      .description('Optional stable id. Auto-generated when absent.'),\n  }),\n  artifactConstructor: () => SpooledJsonArtifact,\n  handler: async (args, ctx) => {\n    const { content, confidence, importance, id } = args as {\n      content: string\n      confidence: number\n      importance: number\n      id?: string\n    }\n    try {\n      const now = DateTime.now()\n      const memory = new Memory({\n        id: id ?? uuidv6(),\n        content,\n        confidence,\n        importance,\n        createdAt: now,\n        updatedAt: now,\n      })\n      await ctx.storeMemory(memory)\n      return JSON.stringify({ ok: true, memory: serialiseMemory(memory) }, null, 2)\n    } catch (err) {\n      return `Error: ${isError(err) ? err.message : String(err)}`\n    }\n  },\n})\n\n/**\n * Replace an existing {@link @nhtio/adk!Memory} by `id`.\n *\n * @remarks\n * The model supplies `id` plus any subset of `content` / `confidence` / `importance`; fields\n * left undefined retain their prior values. `updatedAt` is always bumped to the current time;\n * `createdAt` is preserved. Returns an error when no memory with the supplied `id` is found.\n */\nexport const updateMemoryTool = new Tool({\n  name: 'update_memory',\n  description:\n    'Update an existing memory by id. Supply any subset of content / confidence / importance — omitted fields retain their prior values. updatedAt is always refreshed.',\n  inputSchema: validator.object({\n    id: validator.string().required().description('Id of the memory to update.'),\n    content: validator.string().optional().description('Replacement content.'),\n    confidence: validator\n      .number()\n      .min(0)\n      .max(1)\n      .optional()\n      .description('Replacement confidence in [0, 1].'),\n    importance: validator\n      .number()\n      .min(0)\n      .max(1)\n      .optional()\n      .description('Replacement importance in [0, 1].'),\n  }),\n  artifactConstructor: () => SpooledJsonArtifact,\n  handler: async (args, ctx) => {\n    const { id, content, confidence, importance } = args as {\n      id: string\n      content?: string\n      confidence?: number\n      importance?: number\n    }\n    try {\n      const memories = await ctx.fetchMemories()\n      const existing = memories.find((m) => m.id === id)\n      if (!existing) {\n        return `Error: No memory found with id \"${id}\".`\n      }\n      const updated = new Memory({\n        id: existing.id,\n        content: content ?? existing.content,\n        confidence: confidence ?? existing.confidence,\n        importance: importance ?? existing.importance,\n        createdAt: existing.createdAt,\n        updatedAt: DateTime.now(),\n      })\n      await ctx.mutateMemory(updated)\n      return JSON.stringify({ ok: true, memory: serialiseMemory(updated) }, null, 2)\n    } catch (err) {\n      return `Error: ${isError(err) ? err.message : String(err)}`\n    }\n  },\n})\n\n/**\n * Remove an existing {@link @nhtio/adk!Memory} by `id`.\n *\n * @remarks\n * Delegates to `ctx.deleteMemory(id)`. Returns `{ ok: true, id }` on success regardless of\n * whether a memory was actually present — `deleteMemory` is idempotent at the ADK level.\n */\nexport const deleteMemoryTool = new Tool({\n  name: 'delete_memory',\n  description: 'Delete a memory by id.',\n  inputSchema: validator.object({\n    id: validator.string().required().description('Id of the memory to delete.'),\n  }),\n  artifactConstructor: () => SpooledJsonArtifact,\n  handler: async (args, ctx) => {\n    const { id } = args as { id: string }\n    try {\n      await ctx.deleteMemory(id)\n      return JSON.stringify({ ok: true, id }, null, 2)\n    } catch (err) {\n      return `Error: ${isError(err) ? err.message : String(err)}`\n    }\n  },\n})\n\n/**\n * Convenience tuple of every memory CRUD tool. Spread into a {@link @nhtio/adk!ToolRegistry} to register\n * the entire category at once: `registry.register(...memoryTools)`.\n */\nexport const memoryTools = [\n  listMemoriesTool,\n  storeMemoryTool,\n  updateMemoryTool,\n  deleteMemoryTool,\n] as const\n"],"mappings":"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"}

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

@@ -0,0 +1,47 @@
+/**
+ * Pre-constructed tools for parsing CSV, TSV, JSON, YAML, and other structured text formats.
+ *
+ * @module @nhtio/adk/batteries/tools/parsing
+ *
+ * @remarks
+ * Pre-constructed bundled tools for the `parsing` category. Import individually, the whole
+ * category, or import every tool via `@nhtio/adk/batteries`.
+ */
+import { Tool, SpooledJsonArtifact } from "../../../common";
+/**
+ * Parse a CSV or TSV string into a JSON array.
+ *
+ * @remarks
+ * With `has_header: true` (default), each row becomes an object keyed by column name. Without a
+ * header, rows are returned as positional arrays. `delimiter` auto-detects when omitted; pass
+ * `"\t"` for TSV. Rows are clipped to `limit` (default 1000, max 10000). Parse warnings are
+ * prepended to the output.
+ */
+export declare const parseCsvTool: Tool<SpooledJsonArtifact<unknown>>;
+/**
+ * Parse a YAML string into JSON.
+ *
+ * @remarks
+ * Returns a pretty-printed JSON representation of the parsed YAML document. Invalid YAML
+ * returns an error string.
+ */
+export declare const parseYamlTool: Tool<SpooledJsonArtifact<unknown>>;
+/**
+ * Extract key-value pairs from text.
+ *
+ * @remarks
+ * Handles `.env` files, config files, and query strings. `kv_delimiter` chooses the
+ * key→value separator (`=`, `:`, or `auto`); `pair_delimiter` selects how pairs are separated
+ * (`newline`, `comma`, `semicolon`, `ampersand`). Surrounding single or double quotes around
+ * values are stripped. Comment lines starting with `#` are skipped by default.
+ */
+export declare const parseKvTool: Tool<SpooledJsonArtifact<unknown>>;
+/**
+ * Detect the most likely field delimiter in a CSV-like text sample.
+ *
+ * @remarks
+ * Tries comma, tab, semicolon, pipe, and colon. Scores each by mean field count divided by
+ * variance (so consistent row widths beat noisy splits). Looks at up to the first 20 lines of
+ * the first 5000 characters.
+ */
+export declare const detectDelimiterTool: Tool<import("../../../common").SpooledArtifact>;

package/batteries/tools/parsing.cjs

@@ -0,0 +1,191 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_chunk = require("../../chunk-KmRHZBOW.js");
+const require_tool_registry = require("../../tool_registry-Dkfprsck.js");
+require("../../common-Od8edUXU.js");
+const require_tool = require("../../tool-COSeH8I6.js");
+const require_spooled_markdown_artifact = require("../../spooled_markdown_artifact-RRB113sy.js");
+require("../../guards.cjs");
+let _nhtio_validation = require("@nhtio/validation");
+let js_yaml = require("js-yaml");
+let papaparse = require("papaparse");
+papaparse = require_chunk.__toESM(papaparse);
+//#region src/batteries/tools/parsing/index.ts
+/**
+* Pre-constructed tools for parsing CSV, TSV, JSON, YAML, and other structured text formats.
+*
+* @module @nhtio/adk/batteries/tools/parsing
+*
+* @remarks
+* Pre-constructed bundled tools for the `parsing` category. Import individually, the whole
+* category, or import every tool via `@nhtio/adk/batteries`.
+*/
+/**
+* Parse a CSV or TSV string into a JSON array.
+*
+* @remarks
+* With `has_header: true` (default), each row becomes an object keyed by column name. Without a
+* header, rows are returned as positional arrays. `delimiter` auto-detects when omitted; pass
+* `"\t"` for TSV. Rows are clipped to `limit` (default 1000, max 10000). Parse warnings are
+* prepended to the output.
+*/
+var parseCsvTool = new require_tool.Tool({
+	name: "parse_csv",
+	description: "Parse a CSV or TSV string into a JSON array. With a header row, returns objects keyed by column name. Without, returns arrays of values.",
+	inputSchema: _nhtio_validation.validator.object({
+		text: _nhtio_validation.validator.string().required().description("CSV or TSV text to parse"),
+		has_header: _nhtio_validation.validator.boolean().default(true).description("First row is a header row (default: true)"),
+		delimiter: _nhtio_validation.validator.string().default("").allow("").description("Field delimiter — auto-detected if omitted. Use \"\\t\" for TSV."),
+		limit: _nhtio_validation.validator.number().default(1e3).description("Maximum rows to return (default: 1000)")
+	}),
+	artifactConstructor: () => require_spooled_markdown_artifact.SpooledJsonArtifact,
+	handler: async (args) => {
+		const { text, has_header: hasHeader, delimiter, limit: rawLimit } = args;
+		const limit = Math.min(1e4, Math.max(1, Math.floor(rawLimit)));
+		try {
+			const result = papaparse.default.parse(text.trim(), {
+				header: hasHeader,
+				delimiter: delimiter || void 0,
+				skipEmptyLines: true,
+				dynamicTyping: true
+			});
+			const rows = result.data.slice(0, limit);
+			const warnings = result.errors.length > 0 ? `Parse warnings: ${result.errors.slice(0, 3).map((e) => e.message).join("; ")}\n\n` : "";
+			const truncated = result.data.length > limit ? `\n\n(Showing ${limit} of ${result.data.length} rows)` : "";
+			return warnings + JSON.stringify(rows, null, 2) + truncated;
+		} catch (err) {
+			return `Error: ${require_tool_registry.isError(err) ? err.message : String(err)}`;
+		}
+	}
+});
+/**
+* Parse a YAML string into JSON.
+*
+* @remarks
+* Returns a pretty-printed JSON representation of the parsed YAML document. Invalid YAML
+* returns an error string.
+*/
+var parseYamlTool = new require_tool.Tool({
+	name: "parse_yaml",
+	description: "Parse a YAML string and return the equivalent JSON.",
+	inputSchema: _nhtio_validation.validator.object({ text: _nhtio_validation.validator.string().required().description("YAML text to parse") }),
+	artifactConstructor: () => require_spooled_markdown_artifact.SpooledJsonArtifact,
+	handler: async (args) => {
+		const { text } = args;
+		try {
+			const parsed = (0, js_yaml.load)(text);
+			return JSON.stringify(parsed, null, 2);
+		} catch (err) {
+			return `Error: Invalid YAML — ${require_tool_registry.isError(err) ? err.message : String(err)}`;
+		}
+	}
+});
+/**
+* Extract key-value pairs from text.
+*
+* @remarks
+* Handles `.env` files, config files, and query strings. `kv_delimiter` chooses the
+* key→value separator (`=`, `:`, or `auto`); `pair_delimiter` selects how pairs are separated
+* (`newline`, `comma`, `semicolon`, `ampersand`). Surrounding single or double quotes around
+* values are stripped. Comment lines starting with `#` are skipped by default.
+*/
+var parseKvTool = new require_tool.Tool({
+	name: "parse_kv",
+	description: "Extract key-value pairs from text (e.g. .env files, config files, query strings). Returns a JSON object.",
+	inputSchema: _nhtio_validation.validator.object({
+		text: _nhtio_validation.validator.string().required().description("Text containing key-value pairs"),
+		kv_delimiter: _nhtio_validation.validator.string().valid("=", ":", "auto").default("auto").description("Separator between key and value (default: auto-detect)"),
+		pair_delimiter: _nhtio_validation.validator.string().valid("newline", "comma", "semicolon", "ampersand").default("newline").description("Separator between pairs (default: newline)"),
+		skip_comments: _nhtio_validation.validator.boolean().default(true).description("Skip lines starting with # (default: true)")
+	}),
+	artifactConstructor: () => require_spooled_markdown_artifact.SpooledJsonArtifact,
+	handler: async (args) => {
+		const { text, kv_delimiter: kvDelim, pair_delimiter: pairDelimKey, skip_comments: skipComments } = args;
+		const pairDelim = {
+			newline: "\n",
+			comma: ",",
+			semicolon: ";",
+			ampersand: "&"
+		}[pairDelimKey] ?? "\n";
+		const result = {};
+		for (const raw of text.split(pairDelim)) {
+			const line = raw.trim();
+			if (line === "") continue;
+			if (skipComments && line.startsWith("#")) continue;
+			const delim = kvDelim === "auto" ? line.includes("=") ? "=" : line.includes(":") ? ":" : null : kvDelim;
+			if (!delim) continue;
+			const sepIdx = line.indexOf(delim);
+			if (sepIdx === -1) continue;
+			const key = line.slice(0, sepIdx).trim();
+			let value = line.slice(sepIdx + delim.length).trim();
+			if (value.startsWith("\"") && value.endsWith("\"") || value.startsWith("'") && value.endsWith("'")) value = value.slice(1, -1);
+			if (key) result[key] = value;
+		}
+		return JSON.stringify(result, null, 2);
+	}
+});
+/**
+* Detect the most likely field delimiter in a CSV-like text sample.
+*
+* @remarks
+* Tries comma, tab, semicolon, pipe, and colon. Scores each by mean field count divided by
+* variance (so consistent row widths beat noisy splits). Looks at up to the first 20 lines of
+* the first 5000 characters.
+*/
+var detectDelimiterTool = new require_tool.Tool({
+	name: "detect_delimiter",
+	description: "Detect the most likely field delimiter in a CSV-like text sample.",
+	inputSchema: _nhtio_validation.validator.object({ text: _nhtio_validation.validator.string().required().description("Sample of the delimited text to analyze") }),
+	handler: async (args) => {
+		const { text } = args;
+		const lines = text.slice(0, 5e3).split("\n").map((l) => l.trim()).filter((l) => l.length > 0).slice(0, 20);
+		if (lines.length === 0) return "Error: No lines to analyze.";
+		const candidates = [
+			{
+				delim: ",",
+				name: "comma"
+			},
+			{
+				delim: "	",
+				name: "tab"
+			},
+			{
+				delim: ";",
+				name: "semicolon"
+			},
+			{
+				delim: "|",
+				name: "pipe"
+			},
+			{
+				delim: ":",
+				name: "colon"
+			}
+		];
+		let best = {
+			name: "comma",
+			delim: ",",
+			score: -1,
+			avgFields: 0
+		};
+		for (const { delim, name } of candidates) {
+			const counts = lines.map((l) => l.split(delim).length - 1);
+			const avg = counts.reduce((a, b) => a + b, 0) / counts.length;
+			if (avg === 0) continue;
+			const score = avg / (1 + counts.reduce((a, b) => a + (b - avg) ** 2, 0) / counts.length);
+			if (score > best.score) best = {
+				name,
+				delim,
+				score,
+				avgFields: Number.parseFloat((avg + 1).toFixed(1))
+			};
+		}
+		return `Detected delimiter: ${best.name} ("${best.delim === "	" ? "\\t" : best.delim}") — ~${best.avgFields} fields per row`;
+	}
+});
+//#endregion
+exports.detectDelimiterTool = detectDelimiterTool;
+exports.parseCsvTool = parseCsvTool;
+exports.parseKvTool = parseKvTool;
+exports.parseYamlTool = parseYamlTool;
+
+//# sourceMappingURL=parsing.cjs.map

package/batteries/tools/parsing.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"parsing.cjs","names":[],"sources":["../../../src/batteries/tools/parsing/index.ts"],"sourcesContent":["/**\n * Pre-constructed tools for parsing CSV, TSV, JSON, YAML, and other structured text formats.\n *\n * @module @nhtio/adk/batteries/tools/parsing\n *\n * @remarks\n * Pre-constructed bundled tools for the `parsing` category. Import individually, the whole\n * category, or import every tool via `@nhtio/adk/batteries`.\n */\n\nimport { load as parseYaml } from 'js-yaml'\nimport { default as Papa } from 'papaparse'\nimport { isError } from '@nhtio/adk/guards'\nimport { validator } from '@nhtio/validation'\nimport { Tool, SpooledJsonArtifact } from '@nhtio/adk/common'\n\n/**\n * Parse a CSV or TSV string into a JSON array.\n *\n * @remarks\n * With `has_header: true` (default), each row becomes an object keyed by column name. Without a\n * header, rows are returned as positional arrays. `delimiter` auto-detects when omitted; pass\n * `\"\\t\"` for TSV. Rows are clipped to `limit` (default 1000, max 10000). Parse warnings are\n * prepended to the output.\n */\nexport const parseCsvTool = new Tool({\n  name: 'parse_csv',\n  description:\n    'Parse a CSV or TSV string into a JSON array. With a header row, returns objects keyed by column name. Without, returns arrays of values.',\n  inputSchema: validator.object({\n    text: validator.string().required().description('CSV or TSV text to parse'),\n    has_header: validator\n      .boolean()\n      .default(true)\n      .description('First row is a header row (default: true)'),\n    delimiter: validator\n      .string()\n      .default('')\n      .allow('')\n      .description('Field delimiter — auto-detected if omitted. Use \"\\\\t\" for TSV.'),\n    limit: validator.number().default(1000).description('Maximum rows to return (default: 1000)'),\n  }),\n  artifactConstructor: () => SpooledJsonArtifact,\n  handler: async (args) => {\n    const {\n      text,\n      has_header: hasHeader,\n      delimiter,\n      limit: rawLimit,\n    } = args as {\n      text: string\n      has_header: boolean\n      delimiter: string\n      limit: number\n    }\n    const limit = Math.min(10_000, Math.max(1, Math.floor(rawLimit)))\n\n    try {\n      const result = Papa.parse<unknown>(text.trim(), {\n        header: hasHeader,\n        delimiter: delimiter || undefined,\n        skipEmptyLines: true,\n        dynamicTyping: true,\n      })\n\n      const rows = (result.data as unknown[]).slice(0, limit)\n      const warnings =\n        result.errors.length > 0\n          ? `Parse warnings: ${result.errors\n              .slice(0, 3)\n              .map((e) => e.message)\n              .join('; ')}\\n\\n`\n          : ''\n      const truncated =\n        result.data.length > limit ? `\\n\\n(Showing ${limit} of ${result.data.length} rows)` : ''\n\n      return warnings + JSON.stringify(rows, null, 2) + truncated\n    } catch (err) {\n      return `Error: ${isError(err) ? err.message : String(err)}`\n    }\n  },\n})\n\n/**\n * Parse a YAML string into JSON.\n *\n * @remarks\n * Returns a pretty-printed JSON representation of the parsed YAML document. Invalid YAML\n * returns an error string.\n */\nexport const parseYamlTool = new Tool({\n  name: 'parse_yaml',\n  description: 'Parse a YAML string and return the equivalent JSON.',\n  inputSchema: validator.object({\n    text: validator.string().required().description('YAML text to parse'),\n  }),\n  artifactConstructor: () => SpooledJsonArtifact,\n  handler: async (args) => {\n    const { text } = args as { text: string }\n    try {\n      const parsed = parseYaml(text)\n      return JSON.stringify(parsed, null, 2)\n    } catch (err) {\n      return `Error: Invalid YAML — ${isError(err) ? err.message : String(err)}`\n    }\n  },\n})\n\n/**\n * Extract key-value pairs from text.\n *\n * @remarks\n * Handles `.env` files, config files, and query strings. `kv_delimiter` chooses the\n * key→value separator (`=`, `:`, or `auto`); `pair_delimiter` selects how pairs are separated\n * (`newline`, `comma`, `semicolon`, `ampersand`). Surrounding single or double quotes around\n * values are stripped. Comment lines starting with `#` are skipped by default.\n */\nexport const parseKvTool = new Tool({\n  name: 'parse_kv',\n  description:\n    'Extract key-value pairs from text (e.g. .env files, config files, query strings). Returns a JSON object.',\n  inputSchema: validator.object({\n    text: validator.string().required().description('Text containing key-value pairs'),\n    kv_delimiter: validator\n      .string()\n      .valid('=', ':', 'auto')\n      .default('auto')\n      .description('Separator between key and value (default: auto-detect)'),\n    pair_delimiter: validator\n      .string()\n      .valid('newline', 'comma', 'semicolon', 'ampersand')\n      .default('newline')\n      .description('Separator between pairs (default: newline)'),\n    skip_comments: validator\n      .boolean()\n      .default(true)\n      .description('Skip lines starting with # (default: true)'),\n  }),\n  artifactConstructor: () => SpooledJsonArtifact,\n  handler: async (args) => {\n    const {\n      text,\n      kv_delimiter: kvDelim,\n      pair_delimiter: pairDelimKey,\n      skip_comments: skipComments,\n    } = args as {\n      text: string\n      kv_delimiter: string\n      pair_delimiter: string\n      skip_comments: boolean\n    }\n\n    const pairDelimMap: Record<string, string> = {\n      newline: '\\n',\n      comma: ',',\n      semicolon: ';',\n      ampersand: '&',\n    }\n    const pairDelim = pairDelimMap[pairDelimKey] ?? '\\n'\n\n    const result: Record<string, string> = {}\n\n    for (const raw of text.split(pairDelim)) {\n      const line = raw.trim()\n      if (line === '') continue\n      if (skipComments && line.startsWith('#')) continue\n\n      const delim =\n        kvDelim === 'auto' ? (line.includes('=') ? '=' : line.includes(':') ? ':' : null) : kvDelim\n      if (!delim) continue\n\n      const sepIdx = line.indexOf(delim)\n      if (sepIdx === -1) continue\n\n      const key = line.slice(0, sepIdx).trim()\n      let value = line.slice(sepIdx + delim.length).trim()\n\n      if (\n        (value.startsWith('\"') && value.endsWith('\"')) ||\n        (value.startsWith(\"'\") && value.endsWith(\"'\"))\n      ) {\n        value = value.slice(1, -1)\n      }\n\n      if (key) result[key] = value\n    }\n\n    return JSON.stringify(result, null, 2)\n  },\n})\n\n/**\n * Detect the most likely field delimiter in a CSV-like text sample.\n *\n * @remarks\n * Tries comma, tab, semicolon, pipe, and colon. Scores each by mean field count divided by\n * variance (so consistent row widths beat noisy splits). Looks at up to the first 20 lines of\n * the first 5000 characters.\n */\nexport const detectDelimiterTool = new Tool({\n  name: 'detect_delimiter',\n  description: 'Detect the most likely field delimiter in a CSV-like text sample.',\n  inputSchema: validator.object({\n    text: validator.string().required().description('Sample of the delimited text to analyze'),\n  }),\n  handler: async (args) => {\n    const { text } = args as { text: string }\n    const sample = text.slice(0, 5000)\n    const lines = sample\n      .split('\\n')\n      .map((l) => l.trim())\n      .filter((l) => l.length > 0)\n      .slice(0, 20)\n\n    if (lines.length === 0) return 'Error: No lines to analyze.'\n\n    const candidates: Array<{ delim: string; name: string }> = [\n      { delim: ',', name: 'comma' },\n      { delim: '\\t', name: 'tab' },\n      { delim: ';', name: 'semicolon' },\n      { delim: '|', name: 'pipe' },\n      { delim: ':', name: 'colon' },\n    ]\n\n    let best = { name: 'comma', delim: ',', score: -1, avgFields: 0 }\n\n    for (const { delim, name } of candidates) {\n      const counts = lines.map((l) => l.split(delim).length - 1)\n      const avg = counts.reduce((a, b) => a + b, 0) / counts.length\n      if (avg === 0) continue\n      const fieldVariance = counts.reduce((a, b) => a + (b - avg) ** 2, 0) / counts.length\n      const score = avg / (1 + fieldVariance)\n      if (score > best.score) {\n        best = { name, delim, score, avgFields: Number.parseFloat((avg + 1).toFixed(1)) }\n      }\n    }\n\n    return `Detected delimiter: ${best.name} (\"${best.delim === '\\t' ? '\\\\t' : best.delim}\") — ~${best.avgFields} fields per row`\n  },\n})\n"],"mappings":"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"}