@nhtio/adk 0.1.0-master-f0aa531d

package/batteries/tools/retrievables.mjs

@@ -0,0 +1,209 @@
+import { o as isError } from "../../tool_registry-DqLOyGyG.mjs";
+import { i as Retrievable } from "../../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/retrievables/index.ts
+/**
+* Pre-constructed CRUD tools for model-visible retrievable and RAG-record management.
+*
+* @module @nhtio/adk/batteries/tools/retrievables
+*
+* @remarks
+* Pre-constructed CRUD tools that expose the ADK's {@link @nhtio/adk!Retrievable} surface to the
+* model. Each tool delegates to the corresponding callback on the active
+* {@link @nhtio/adk!DispatchContext} (`fetchRetrievables`, `storeRetrievable`, `mutateRetrievable`,
+* `deleteRetrievable`) — the persistence layer is whatever the consumer wired into the
+* runner.
+*
+* Retrievables are RAG records and carry an explicit `trustTier` that drives the LLM
+* battery's rendering envelope. Exposing these CRUD tools to the model is a deliberate
+* deployer decision; the trust tier the model declares when creating or updating a record
+* is honoured verbatim by the persistence layer. The deployer is responsible for choosing
+* whether to register all four tools, only the read-only `list_retrievables`, or any subset
+* thereof — that registration choice is exactly the trust boundary documented in the
+* Retrievable battery contract.
+*
+* 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 listRetrievablesTool} — read-only list of every retrievable currently held by
+*   the context.
+* - {@link storeRetrievableTool} — create a new retrievable record (auto-generates `id` /
+*   `createdAt` / `updatedAt` unless explicit values are supplied).
+* - {@link updateRetrievableTool} — replace an existing retrievable by `id`. Bumps
+*   `updatedAt`.
+* - {@link deleteRetrievableTool} — remove a retrievable by `id`.
+*/
+var TRUST_TIERS = [
+	"first-party",
+	"third-party-public",
+	"third-party-private"
+];
+var serialiseRetrievable = (r) => ({
+	id: r.id,
+	content: r.content.toString(),
+	trustTier: r.trustTier,
+	source: r.source,
+	kind: r.kind,
+	score: r.score,
+	createdAt: r.createdAt.toISO(),
+	updatedAt: r.updatedAt.toISO()
+});
+/**
+* List every retrievable record currently held by the active execution context.
+*
+* @remarks
+* Delegates to `ctx.fetchRetrievables()`. Returns a JSON-encoded array of retrievable records
+* (id, content, trustTier, source, kind, score, createdAt, updatedAt).
+*/
+var listRetrievablesTool = new Tool({
+	name: "list_retrievables",
+	description: "List every retrievable record currently available to the agent. Returns a JSON array of records with id, content, trustTier, source, kind, score, createdAt, and updatedAt.",
+	inputSchema: validator.object({}),
+	artifactConstructor: () => SpooledJsonArtifact,
+	handler: async (_args, ctx) => {
+		try {
+			const retrievables = await ctx.fetchRetrievables();
+			return JSON.stringify(retrievables.map(serialiseRetrievable), null, 2);
+		} catch (err) {
+			return `Error: ${isError(err) ? err.message : String(err)}`;
+		}
+	}
+});
+/**
+* Create a new {@link @nhtio/adk!Retrievable} record and persist it via the context's `storeRetrievable`
+* callback.
+*
+* @remarks
+* When `id` is omitted, a UUID v6 is generated. When `createdAt` / `updatedAt` are omitted,
+* the current time is used. The model must declare `trustTier` explicitly — there is no
+* default; the choice is consciously the model's, exposed by the deployer's decision to
+* register this tool.
+*/
+var storeRetrievableTool = new Tool({
+	name: "store_retrievable",
+	description: "Store a new retrievable (RAG) record. The trustTier MUST be one of 'first-party' (deployer-vetted), 'third-party-public' (open-web), or 'third-party-private' (user uploads). id and timestamps are auto-generated if omitted.",
+	inputSchema: validator.object({
+		content: validator.string().required().description("The retrievable content as a plain string."),
+		trustTier: validator.string().valid(...TRUST_TIERS).required().description("Trust tier: 'first-party' for deployer-vetted material, 'third-party-public' for open-web or public APIs, 'third-party-private' for user uploads or partner APIs."),
+		source: validator.string().optional().description("Optional provenance string: URL, document path, KB id, etc."),
+		kind: validator.string().optional().description("Optional semantic label: 'policy', 'reference', 'web-page', 'pdf', etc."),
+		score: validator.number().min(0).max(1).optional().description("Optional relevance / similarity score in [0, 1]."),
+		id: validator.string().optional().description("Optional stable id. Auto-generated when absent.")
+	}),
+	artifactConstructor: () => SpooledJsonArtifact,
+	handler: async (args, ctx) => {
+		const { content, trustTier, source, kind, score, id } = args;
+		try {
+			const now = DateTime.now();
+			const retrievable = new Retrievable({
+				id: id ?? v6(),
+				content,
+				trustTier,
+				source,
+				kind,
+				score,
+				createdAt: now,
+				updatedAt: now
+			});
+			await ctx.storeRetrievable(retrievable);
+			return JSON.stringify({
+				ok: true,
+				retrievable: serialiseRetrievable(retrievable)
+			}, null, 2);
+		} catch (err) {
+			return `Error: ${isError(err) ? err.message : String(err)}`;
+		}
+	}
+});
+/**
+* Replace an existing {@link @nhtio/adk!Retrievable} by `id`.
+*
+* @remarks
+* The model supplies `id` plus any subset of `content` / `trustTier` / `source` / `kind` /
+* `score`; omitted fields retain their prior values. `updatedAt` is always bumped;
+* `createdAt` is preserved. Returns an error when no retrievable with the supplied `id` is
+* found.
+*/
+var updateRetrievableTool = new Tool({
+	name: "update_retrievable",
+	description: "Update an existing retrievable by id. Supply any subset of content / trustTier / source / kind / score — omitted fields retain their prior values. updatedAt is always refreshed.",
+	inputSchema: validator.object({
+		id: validator.string().required().description("Id of the retrievable to update."),
+		content: validator.string().optional().description("Replacement content."),
+		trustTier: validator.string().valid(...TRUST_TIERS).optional().description("Replacement trust tier."),
+		source: validator.string().optional().description("Replacement provenance string."),
+		kind: validator.string().optional().description("Replacement semantic label."),
+		score: validator.number().min(0).max(1).optional().description("Replacement score in [0, 1].")
+	}),
+	artifactConstructor: () => SpooledJsonArtifact,
+	handler: async (args, ctx) => {
+		const { id, content, trustTier, source, kind, score } = args;
+		try {
+			const existing = (await ctx.fetchRetrievables()).find((r) => r.id === id);
+			if (!existing) return `Error: No retrievable found with id "${id}".`;
+			const updated = new Retrievable({
+				id: existing.id,
+				content: content ?? existing.content,
+				trustTier: trustTier ?? existing.trustTier,
+				source: source ?? existing.source,
+				kind: kind ?? existing.kind,
+				score: score ?? existing.score,
+				createdAt: existing.createdAt,
+				updatedAt: DateTime.now()
+			});
+			await ctx.mutateRetrievable(updated);
+			return JSON.stringify({
+				ok: true,
+				retrievable: serialiseRetrievable(updated)
+			}, null, 2);
+		} catch (err) {
+			return `Error: ${isError(err) ? err.message : String(err)}`;
+		}
+	}
+});
+/**
+* Remove an existing {@link @nhtio/adk!Retrievable} by `id`.
+*
+* @remarks
+* Delegates to `ctx.deleteRetrievable(id)`. Returns `{ ok: true, id }` on success regardless
+* of whether a retrievable was actually present — `deleteRetrievable` is idempotent at the
+* ADK level.
+*/
+var deleteRetrievableTool = new Tool({
+	name: "delete_retrievable",
+	description: "Delete a retrievable by id.",
+	inputSchema: validator.object({ id: validator.string().required().description("Id of the retrievable to delete.") }),
+	artifactConstructor: () => SpooledJsonArtifact,
+	handler: async (args, ctx) => {
+		const { id } = args;
+		try {
+			await ctx.deleteRetrievable(id);
+			return JSON.stringify({
+				ok: true,
+				id
+			}, null, 2);
+		} catch (err) {
+			return `Error: ${isError(err) ? err.message : String(err)}`;
+		}
+	}
+});
+/**
+* Convenience tuple of every retrievable CRUD tool. Spread into a {@link @nhtio/adk!ToolRegistry} to
+* register the entire category at once.
+*/
+var retrievableTools = [
+	listRetrievablesTool,
+	storeRetrievableTool,
+	updateRetrievableTool,
+	deleteRetrievableTool
+];
+//#endregion
+export { deleteRetrievableTool, listRetrievablesTool, retrievableTools, storeRetrievableTool, updateRetrievableTool };
+
+//# sourceMappingURL=retrievables.mjs.map

package/batteries/tools/retrievables.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"retrievables.mjs","names":[],"sources":["../../../src/batteries/tools/retrievables/index.ts"],"sourcesContent":["/**\n * Pre-constructed CRUD tools for model-visible retrievable and RAG-record management.\n *\n * @module @nhtio/adk/batteries/tools/retrievables\n *\n * @remarks\n * Pre-constructed CRUD tools that expose the ADK's {@link @nhtio/adk!Retrievable} surface to the\n * model. Each tool delegates to the corresponding callback on the active\n * {@link @nhtio/adk!DispatchContext} (`fetchRetrievables`, `storeRetrievable`, `mutateRetrievable`,\n * `deleteRetrievable`) — the persistence layer is whatever the consumer wired into the\n * runner.\n *\n * Retrievables are RAG records and carry an explicit `trustTier` that drives the LLM\n * battery's rendering envelope. Exposing these CRUD tools to the model is a deliberate\n * deployer decision; the trust tier the model declares when creating or updating a record\n * is honoured verbatim by the persistence layer. The deployer is responsible for choosing\n * whether to register all four tools, only the read-only `list_retrievables`, or any subset\n * thereof — that registration choice is exactly the trust boundary documented in the\n * Retrievable battery contract.\n *\n * Output is JSON for every tool so consumers can parse the result without re-tokenising —\n * the artifact constructor is set to {@link @nhtio/adk!SpooledJsonArtifact}.\n *\n * Tools:\n * - {@link listRetrievablesTool} — read-only list of every retrievable currently held by\n *   the context.\n * - {@link storeRetrievableTool} — create a new retrievable record (auto-generates `id` /\n *   `createdAt` / `updatedAt` unless explicit values are supplied).\n * - {@link updateRetrievableTool} — replace an existing retrievable by `id`. Bumps\n *   `updatedAt`.\n * - {@link deleteRetrievableTool} — remove a retrievable 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 { Retrievable, SpooledJsonArtifact, Tool } from '@nhtio/adk/common'\n\nconst TRUST_TIERS = ['first-party', 'third-party-public', 'third-party-private'] as const\ntype TrustTier = (typeof TRUST_TIERS)[number]\n\nconst serialiseRetrievable = (r: Retrievable): Record<string, unknown> => ({\n  id: r.id,\n  content: r.content.toString(),\n  trustTier: r.trustTier,\n  source: r.source,\n  kind: r.kind,\n  score: r.score,\n  createdAt: r.createdAt.toISO(),\n  updatedAt: r.updatedAt.toISO(),\n})\n\n/**\n * List every retrievable record currently held by the active execution context.\n *\n * @remarks\n * Delegates to `ctx.fetchRetrievables()`. Returns a JSON-encoded array of retrievable records\n * (id, content, trustTier, source, kind, score, createdAt, updatedAt).\n */\nexport const listRetrievablesTool = new Tool({\n  name: 'list_retrievables',\n  description:\n    'List every retrievable record currently available to the agent. Returns a JSON array of records with id, content, trustTier, source, kind, score, createdAt, and updatedAt.',\n  inputSchema: validator.object({}),\n  artifactConstructor: () => SpooledJsonArtifact,\n  handler: async (_args, ctx) => {\n    try {\n      const retrievables = await ctx.fetchRetrievables()\n      return JSON.stringify(retrievables.map(serialiseRetrievable), 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!Retrievable} record and persist it via the context's `storeRetrievable`\n * 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 must declare `trustTier` explicitly — there is no\n * default; the choice is consciously the model's, exposed by the deployer's decision to\n * register this tool.\n */\nexport const storeRetrievableTool = new Tool({\n  name: 'store_retrievable',\n  description:\n    \"Store a new retrievable (RAG) record. The trustTier MUST be one of 'first-party' (deployer-vetted), 'third-party-public' (open-web), or 'third-party-private' (user uploads). id and timestamps are auto-generated if omitted.\",\n  inputSchema: validator.object({\n    content: validator\n      .string()\n      .required()\n      .description('The retrievable content as a plain string.'),\n    trustTier: validator\n      .string()\n      .valid(...TRUST_TIERS)\n      .required()\n      .description(\n        \"Trust tier: 'first-party' for deployer-vetted material, 'third-party-public' for open-web or public APIs, 'third-party-private' for user uploads or partner APIs.\"\n      ),\n    source: validator\n      .string()\n      .optional()\n      .description('Optional provenance string: URL, document path, KB id, etc.'),\n    kind: validator\n      .string()\n      .optional()\n      .description(\"Optional semantic label: 'policy', 'reference', 'web-page', 'pdf', etc.\"),\n    score: validator\n      .number()\n      .min(0)\n      .max(1)\n      .optional()\n      .description('Optional relevance / similarity score in [0, 1].'),\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, trustTier, source, kind, score, id } = args as {\n      content: string\n      trustTier: TrustTier\n      source?: string\n      kind?: string\n      score?: number\n      id?: string\n    }\n    try {\n      const now = DateTime.now()\n      const retrievable = new Retrievable({\n        id: id ?? uuidv6(),\n        content,\n        trustTier,\n        source,\n        kind,\n        score,\n        createdAt: now,\n        updatedAt: now,\n      })\n      await ctx.storeRetrievable(retrievable)\n      return JSON.stringify({ ok: true, retrievable: serialiseRetrievable(retrievable) }, 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!Retrievable} by `id`.\n *\n * @remarks\n * The model supplies `id` plus any subset of `content` / `trustTier` / `source` / `kind` /\n * `score`; omitted fields retain their prior values. `updatedAt` is always bumped;\n * `createdAt` is preserved. Returns an error when no retrievable with the supplied `id` is\n * found.\n */\nexport const updateRetrievableTool = new Tool({\n  name: 'update_retrievable',\n  description:\n    'Update an existing retrievable by id. Supply any subset of content / trustTier / source / kind / score — omitted fields retain their prior values. updatedAt is always refreshed.',\n  inputSchema: validator.object({\n    id: validator.string().required().description('Id of the retrievable to update.'),\n    content: validator.string().optional().description('Replacement content.'),\n    trustTier: validator\n      .string()\n      .valid(...TRUST_TIERS)\n      .optional()\n      .description('Replacement trust tier.'),\n    source: validator.string().optional().description('Replacement provenance string.'),\n    kind: validator.string().optional().description('Replacement semantic label.'),\n    score: validator.number().min(0).max(1).optional().description('Replacement score in [0, 1].'),\n  }),\n  artifactConstructor: () => SpooledJsonArtifact,\n  handler: async (args, ctx) => {\n    const { id, content, trustTier, source, kind, score } = args as {\n      id: string\n      content?: string\n      trustTier?: TrustTier\n      source?: string\n      kind?: string\n      score?: number\n    }\n    try {\n      const retrievables = await ctx.fetchRetrievables()\n      const existing = retrievables.find((r) => r.id === id)\n      if (!existing) {\n        return `Error: No retrievable found with id \"${id}\".`\n      }\n      const updated = new Retrievable({\n        id: existing.id,\n        content: content ?? existing.content,\n        trustTier: trustTier ?? existing.trustTier,\n        source: source ?? existing.source,\n        kind: kind ?? existing.kind,\n        score: score ?? existing.score,\n        createdAt: existing.createdAt,\n        updatedAt: DateTime.now(),\n      })\n      await ctx.mutateRetrievable(updated)\n      return JSON.stringify({ ok: true, retrievable: serialiseRetrievable(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!Retrievable} by `id`.\n *\n * @remarks\n * Delegates to `ctx.deleteRetrievable(id)`. Returns `{ ok: true, id }` on success regardless\n * of whether a retrievable was actually present — `deleteRetrievable` is idempotent at the\n * ADK level.\n */\nexport const deleteRetrievableTool = new Tool({\n  name: 'delete_retrievable',\n  description: 'Delete a retrievable by id.',\n  inputSchema: validator.object({\n    id: validator.string().required().description('Id of the retrievable to delete.'),\n  }),\n  artifactConstructor: () => SpooledJsonArtifact,\n  handler: async (args, ctx) => {\n    const { id } = args as { id: string }\n    try {\n      await ctx.deleteRetrievable(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 retrievable CRUD tool. Spread into a {@link @nhtio/adk!ToolRegistry} to\n * register the entire category at once.\n */\nexport const retrievableTools = [\n  listRetrievablesTool,\n  storeRetrievableTool,\n  updateRetrievableTool,\n  deleteRetrievableTool,\n] as const\n"],"mappings":"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"}

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

@@ -0,0 +1,64 @@
+/**
+ * Pre-constructed CRUD tools for model-visible standing instruction management.
+ *
+ * @module @nhtio/adk/batteries/tools/standing_instructions
+ *
+ * @remarks
+ * Pre-constructed CRUD tools that expose the ADK's standing-instruction surface to the
+ * model. Each tool delegates to the corresponding callback on the active
+ * {@link @nhtio/adk!DispatchContext} (`standingInstructions` getter, `storeStandingInstruction`,
+ * `deleteStandingInstruction`) — the persistence layer is whatever the consumer wired into
+ * the runner.
+ *
+ * Standing instructions are stored as a {@link Set} of {@link @nhtio/adk!Tokenizable} values keyed by
+ * identity, not by an `id` field — there is no separate "update by id" semantics. The tools
+ * therefore expose only `list` / `add` / `remove`. To replace an existing instruction the
+ * model should `remove` the old value and `add` the new one (the ADK's persistence layer
+ * is free to interpret that pair as an update if appropriate).
+ *
+ * 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 listStandingInstructionsTool} — read-only list of every standing instruction
+ *   currently held by the context (after refreshing from the persistence layer).
+ * - {@link addStandingInstructionTool} — add a new standing instruction.
+ * - {@link removeStandingInstructionTool} — remove a standing instruction by its content
+ *   (exact string match).
+ */
+import { SpooledJsonArtifact, Tool } from "../../../common";
+/**
+ * List every standing instruction currently held by the active execution context.
+ *
+ * @remarks
+ * Calls `ctx.refreshStandingInstructions()` to ensure the local Set is in sync with the
+ * persistence layer, then serialises the resulting strings to a JSON array. The list is
+ * stringly-keyed; the same content string serves as the identifier for subsequent removes.
+ */
+export declare const listStandingInstructionsTool: Tool<SpooledJsonArtifact<unknown>>;
+/**
+ * Add a new standing instruction to the active execution context.
+ *
+ * @remarks
+ * Delegates to `ctx.storeStandingInstruction(content)`. Standing instructions are stored as
+ * a `Set` — adding the same content twice is a no-op at the local level, though the
+ * consumer's persistence callback may interpret it differently.
+ */
+export declare const addStandingInstructionTool: Tool<SpooledJsonArtifact<unknown>>;
+/**
+ * Remove an existing standing instruction by its content string.
+ *
+ * @remarks
+ * Delegates to `ctx.deleteStandingInstruction(content)`. Idempotent — succeeds even when
+ * no matching instruction is currently present.
+ */
+export declare const removeStandingInstructionTool: Tool<SpooledJsonArtifact<unknown>>;
+/**
+ * Convenience tuple of every standing-instruction tool. Spread into a {@link @nhtio/adk!ToolRegistry}
+ * to register the entire category at once.
+ */
+export declare const standingInstructionTools: readonly [
+    Tool<SpooledJsonArtifact<unknown>>,
+    Tool<SpooledJsonArtifact<unknown>>,
+    Tool<SpooledJsonArtifact<unknown>>
+];

package/batteries/tools/standing_instructions.cjs

@@ -0,0 +1,126 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+require("../../chunk-KmRHZBOW.js");
+const require_tool_registry = require("../../tool_registry-Dkfprsck.js");
+require("../../common-Od8edUXU.js");
+const require_tool = require("../../tool-COSeH8I6.js");
+const require_spooled_markdown_artifact = require("../../spooled_markdown_artifact-RRB113sy.js");
+require("../../guards.cjs");
+let _nhtio_validation = require("@nhtio/validation");
+//#region src/batteries/tools/standing_instructions/index.ts
+/**
+* Pre-constructed CRUD tools for model-visible standing instruction management.
+*
+* @module @nhtio/adk/batteries/tools/standing_instructions
+*
+* @remarks
+* Pre-constructed CRUD tools that expose the ADK's standing-instruction surface to the
+* model. Each tool delegates to the corresponding callback on the active
+* {@link @nhtio/adk!DispatchContext} (`standingInstructions` getter, `storeStandingInstruction`,
+* `deleteStandingInstruction`) — the persistence layer is whatever the consumer wired into
+* the runner.
+*
+* Standing instructions are stored as a {@link Set} of {@link @nhtio/adk!Tokenizable} values keyed by
+* identity, not by an `id` field — there is no separate "update by id" semantics. The tools
+* therefore expose only `list` / `add` / `remove`. To replace an existing instruction the
+* model should `remove` the old value and `add` the new one (the ADK's persistence layer
+* is free to interpret that pair as an update if appropriate).
+*
+* 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 listStandingInstructionsTool} — read-only list of every standing instruction
+*   currently held by the context (after refreshing from the persistence layer).
+* - {@link addStandingInstructionTool} — add a new standing instruction.
+* - {@link removeStandingInstructionTool} — remove a standing instruction by its content
+*   (exact string match).
+*/
+/**
+* List every standing instruction currently held by the active execution context.
+*
+* @remarks
+* Calls `ctx.refreshStandingInstructions()` to ensure the local Set is in sync with the
+* persistence layer, then serialises the resulting strings to a JSON array. The list is
+* stringly-keyed; the same content string serves as the identifier for subsequent removes.
+*/
+var listStandingInstructionsTool = new require_tool.Tool({
+	name: "list_standing_instructions",
+	description: "List every standing instruction currently held by the agent. Returns a JSON array of strings. To replace an instruction, remove the old string and add a new one.",
+	inputSchema: _nhtio_validation.validator.object({}),
+	artifactConstructor: () => require_spooled_markdown_artifact.SpooledJsonArtifact,
+	handler: async (_args, ctx) => {
+		try {
+			const items = (await ctx.refreshStandingInstructions()).map((v) => typeof v === "string" ? v : v.toString());
+			return JSON.stringify(items, null, 2);
+		} catch (err) {
+			return `Error: ${require_tool_registry.isError(err) ? err.message : String(err)}`;
+		}
+	}
+});
+/**
+* Add a new standing instruction to the active execution context.
+*
+* @remarks
+* Delegates to `ctx.storeStandingInstruction(content)`. Standing instructions are stored as
+* a `Set` — adding the same content twice is a no-op at the local level, though the
+* consumer's persistence callback may interpret it differently.
+*/
+var addStandingInstructionTool = new require_tool.Tool({
+	name: "add_standing_instruction",
+	description: "Add a new standing instruction. Returns the stored content. Adding an identical instruction that already exists is a no-op.",
+	inputSchema: _nhtio_validation.validator.object({ content: _nhtio_validation.validator.string().required().description("The standing-instruction content as a plain string.") }),
+	artifactConstructor: () => require_spooled_markdown_artifact.SpooledJsonArtifact,
+	handler: async (args, ctx) => {
+		const { content } = args;
+		try {
+			await ctx.storeStandingInstruction(content);
+			return JSON.stringify({
+				ok: true,
+				content
+			}, null, 2);
+		} catch (err) {
+			return `Error: ${require_tool_registry.isError(err) ? err.message : String(err)}`;
+		}
+	}
+});
+/**
+* Remove an existing standing instruction by its content string.
+*
+* @remarks
+* Delegates to `ctx.deleteStandingInstruction(content)`. Idempotent — succeeds even when
+* no matching instruction is currently present.
+*/
+var removeStandingInstructionTool = new require_tool.Tool({
+	name: "remove_standing_instruction",
+	description: "Remove a standing instruction by its exact content string. Idempotent — succeeds even when no match is present.",
+	inputSchema: _nhtio_validation.validator.object({ content: _nhtio_validation.validator.string().required().description("The exact content string of the instruction to remove.") }),
+	artifactConstructor: () => require_spooled_markdown_artifact.SpooledJsonArtifact,
+	handler: async (args, ctx) => {
+		const { content } = args;
+		try {
+			await ctx.deleteStandingInstruction(content);
+			return JSON.stringify({
+				ok: true,
+				content
+			}, null, 2);
+		} catch (err) {
+			return `Error: ${require_tool_registry.isError(err) ? err.message : String(err)}`;
+		}
+	}
+});
+/**
+* Convenience tuple of every standing-instruction tool. Spread into a {@link @nhtio/adk!ToolRegistry}
+* to register the entire category at once.
+*/
+var standingInstructionTools = [
+	listStandingInstructionsTool,
+	addStandingInstructionTool,
+	removeStandingInstructionTool
+];
+//#endregion
+exports.addStandingInstructionTool = addStandingInstructionTool;
+exports.listStandingInstructionsTool = listStandingInstructionsTool;
+exports.removeStandingInstructionTool = removeStandingInstructionTool;
+exports.standingInstructionTools = standingInstructionTools;
+
+//# sourceMappingURL=standing_instructions.cjs.map

package/batteries/tools/standing_instructions.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"standing_instructions.cjs","names":[],"sources":["../../../src/batteries/tools/standing_instructions/index.ts"],"sourcesContent":["/**\n * Pre-constructed CRUD tools for model-visible standing instruction management.\n *\n * @module @nhtio/adk/batteries/tools/standing_instructions\n *\n * @remarks\n * Pre-constructed CRUD tools that expose the ADK's standing-instruction surface to the\n * model. Each tool delegates to the corresponding callback on the active\n * {@link @nhtio/adk!DispatchContext} (`standingInstructions` getter, `storeStandingInstruction`,\n * `deleteStandingInstruction`) — the persistence layer is whatever the consumer wired into\n * the runner.\n *\n * Standing instructions are stored as a {@link Set} of {@link @nhtio/adk!Tokenizable} values keyed by\n * identity, not by an `id` field — there is no separate \"update by id\" semantics. The tools\n * therefore expose only `list` / `add` / `remove`. To replace an existing instruction the\n * model should `remove` the old value and `add` the new one (the ADK's persistence layer\n * is free to interpret that pair as an update if appropriate).\n *\n * Output is JSON for every tool so consumers can parse the result without re-tokenising —\n * the artifact constructor is set to {@link @nhtio/adk!SpooledJsonArtifact}.\n *\n * Tools:\n * - {@link listStandingInstructionsTool} — read-only list of every standing instruction\n *   currently held by the context (after refreshing from the persistence layer).\n * - {@link addStandingInstructionTool} — add a new standing instruction.\n * - {@link removeStandingInstructionTool} — remove a standing instruction by its content\n *   (exact string match).\n */\n\nimport { isError } from '@nhtio/adk/guards'\nimport { validator } from '@nhtio/validation'\nimport { SpooledJsonArtifact, Tool } from '@nhtio/adk/common'\n\n/**\n * List every standing instruction currently held by the active execution context.\n *\n * @remarks\n * Calls `ctx.refreshStandingInstructions()` to ensure the local Set is in sync with the\n * persistence layer, then serialises the resulting strings to a JSON array. The list is\n * stringly-keyed; the same content string serves as the identifier for subsequent removes.\n */\nexport const listStandingInstructionsTool = new Tool({\n  name: 'list_standing_instructions',\n  description:\n    'List every standing instruction currently held by the agent. Returns a JSON array of strings. To replace an instruction, remove the old string and add a new one.',\n  inputSchema: validator.object({}),\n  artifactConstructor: () => SpooledJsonArtifact,\n  handler: async (_args, ctx) => {\n    try {\n      const refreshed = await ctx.refreshStandingInstructions()\n      const items = refreshed.map((v) => (typeof v === 'string' ? v : v.toString()))\n      return JSON.stringify(items, null, 2)\n    } catch (err) {\n      return `Error: ${isError(err) ? err.message : String(err)}`\n    }\n  },\n})\n\n/**\n * Add a new standing instruction to the active execution context.\n *\n * @remarks\n * Delegates to `ctx.storeStandingInstruction(content)`. Standing instructions are stored as\n * a `Set` — adding the same content twice is a no-op at the local level, though the\n * consumer's persistence callback may interpret it differently.\n */\nexport const addStandingInstructionTool = new Tool({\n  name: 'add_standing_instruction',\n  description:\n    'Add a new standing instruction. Returns the stored content. Adding an identical instruction that already exists is a no-op.',\n  inputSchema: validator.object({\n    content: validator\n      .string()\n      .required()\n      .description('The standing-instruction content as a plain string.'),\n  }),\n  artifactConstructor: () => SpooledJsonArtifact,\n  handler: async (args, ctx) => {\n    const { content } = args as { content: string }\n    try {\n      await ctx.storeStandingInstruction(content)\n      return JSON.stringify({ ok: true, content }, null, 2)\n    } catch (err) {\n      return `Error: ${isError(err) ? err.message : String(err)}`\n    }\n  },\n})\n\n/**\n * Remove an existing standing instruction by its content string.\n *\n * @remarks\n * Delegates to `ctx.deleteStandingInstruction(content)`. Idempotent — succeeds even when\n * no matching instruction is currently present.\n */\nexport const removeStandingInstructionTool = new Tool({\n  name: 'remove_standing_instruction',\n  description:\n    'Remove a standing instruction by its exact content string. Idempotent — succeeds even when no match is present.',\n  inputSchema: validator.object({\n    content: validator\n      .string()\n      .required()\n      .description('The exact content string of the instruction to remove.'),\n  }),\n  artifactConstructor: () => SpooledJsonArtifact,\n  handler: async (args, ctx) => {\n    const { content } = args as { content: string }\n    try {\n      await ctx.deleteStandingInstruction(content)\n      return JSON.stringify({ ok: true, content }, null, 2)\n    } catch (err) {\n      return `Error: ${isError(err) ? err.message : String(err)}`\n    }\n  },\n})\n\n/**\n * Convenience tuple of every standing-instruction tool. Spread into a {@link @nhtio/adk!ToolRegistry}\n * to register the entire category at once.\n */\nexport const standingInstructionTools = [\n  listStandingInstructionsTool,\n  addStandingInstructionTool,\n  removeStandingInstructionTool,\n] as const\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyCA,IAAa,+BAA+B,IAAI,aAAA,KAAK;CACnD,MAAM;CACN,aACE;CACF,aAAa,kBAAA,UAAU,OAAO,CAAC,CAAC;CAChC,2BAA2B,kCAAA;CAC3B,SAAS,OAAO,OAAO,QAAQ;EAC7B,IAAI;GAEF,MAAM,SAAQ,MADU,IAAI,4BAA4B,GAChC,KAAK,MAAO,OAAO,MAAM,WAAW,IAAI,EAAE,SAAS,CAAE;GAC7E,OAAO,KAAK,UAAU,OAAO,MAAM,CAAC;EACtC,SAAS,KAAK;GACZ,OAAO,UAAU,sBAAA,QAAQ,GAAG,IAAI,IAAI,UAAU,OAAO,GAAG;EAC1D;CACF;AACF,CAAC;;;;;;;;;AAUD,IAAa,6BAA6B,IAAI,aAAA,KAAK;CACjD,MAAM;CACN,aACE;CACF,aAAa,kBAAA,UAAU,OAAO,EAC5B,SAAS,kBAAA,UACN,OAAO,EACP,SAAS,EACT,YAAY,qDAAqD,EACtE,CAAC;CACD,2BAA2B,kCAAA;CAC3B,SAAS,OAAO,MAAM,QAAQ;EAC5B,MAAM,EAAE,YAAY;EACpB,IAAI;GACF,MAAM,IAAI,yBAAyB,OAAO;GAC1C,OAAO,KAAK,UAAU;IAAE,IAAI;IAAM;GAAQ,GAAG,MAAM,CAAC;EACtD,SAAS,KAAK;GACZ,OAAO,UAAU,sBAAA,QAAQ,GAAG,IAAI,IAAI,UAAU,OAAO,GAAG;EAC1D;CACF;AACF,CAAC;;;;;;;;AASD,IAAa,gCAAgC,IAAI,aAAA,KAAK;CACpD,MAAM;CACN,aACE;CACF,aAAa,kBAAA,UAAU,OAAO,EAC5B,SAAS,kBAAA,UACN,OAAO,EACP,SAAS,EACT,YAAY,wDAAwD,EACzE,CAAC;CACD,2BAA2B,kCAAA;CAC3B,SAAS,OAAO,MAAM,QAAQ;EAC5B,MAAM,EAAE,YAAY;EACpB,IAAI;GACF,MAAM,IAAI,0BAA0B,OAAO;GAC3C,OAAO,KAAK,UAAU;IAAE,IAAI;IAAM;GAAQ,GAAG,MAAM,CAAC;EACtD,SAAS,KAAK;GACZ,OAAO,UAAU,sBAAA,QAAQ,GAAG,IAAI,IAAI,UAAU,OAAO,GAAG;EAC1D;CACF;AACF,CAAC;;;;;AAMD,IAAa,2BAA2B;CACtC;CACA;CACA;AACF"}

package/batteries/tools/standing_instructions.mjs

@@ -0,0 +1,121 @@
+import { o as isError } from "../../tool_registry-DqLOyGyG.mjs";
+import "../../common-DeZaonK1.mjs";
+import { t as Tool } from "../../tool-D2WB1EA1.mjs";
+import { n as SpooledJsonArtifact } from "../../spooled_markdown_artifact-BpUJol0W.mjs";
+import "../../guards.mjs";
+import { validator } from "@nhtio/validation";
+//#region src/batteries/tools/standing_instructions/index.ts
+/**
+* Pre-constructed CRUD tools for model-visible standing instruction management.
+*
+* @module @nhtio/adk/batteries/tools/standing_instructions
+*
+* @remarks
+* Pre-constructed CRUD tools that expose the ADK's standing-instruction surface to the
+* model. Each tool delegates to the corresponding callback on the active
+* {@link @nhtio/adk!DispatchContext} (`standingInstructions` getter, `storeStandingInstruction`,
+* `deleteStandingInstruction`) — the persistence layer is whatever the consumer wired into
+* the runner.
+*
+* Standing instructions are stored as a {@link Set} of {@link @nhtio/adk!Tokenizable} values keyed by
+* identity, not by an `id` field — there is no separate "update by id" semantics. The tools
+* therefore expose only `list` / `add` / `remove`. To replace an existing instruction the
+* model should `remove` the old value and `add` the new one (the ADK's persistence layer
+* is free to interpret that pair as an update if appropriate).
+*
+* 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 listStandingInstructionsTool} — read-only list of every standing instruction
+*   currently held by the context (after refreshing from the persistence layer).
+* - {@link addStandingInstructionTool} — add a new standing instruction.
+* - {@link removeStandingInstructionTool} — remove a standing instruction by its content
+*   (exact string match).
+*/
+/**
+* List every standing instruction currently held by the active execution context.
+*
+* @remarks
+* Calls `ctx.refreshStandingInstructions()` to ensure the local Set is in sync with the
+* persistence layer, then serialises the resulting strings to a JSON array. The list is
+* stringly-keyed; the same content string serves as the identifier for subsequent removes.
+*/
+var listStandingInstructionsTool = new Tool({
+	name: "list_standing_instructions",
+	description: "List every standing instruction currently held by the agent. Returns a JSON array of strings. To replace an instruction, remove the old string and add a new one.",
+	inputSchema: validator.object({}),
+	artifactConstructor: () => SpooledJsonArtifact,
+	handler: async (_args, ctx) => {
+		try {
+			const items = (await ctx.refreshStandingInstructions()).map((v) => typeof v === "string" ? v : v.toString());
+			return JSON.stringify(items, null, 2);
+		} catch (err) {
+			return `Error: ${isError(err) ? err.message : String(err)}`;
+		}
+	}
+});
+/**
+* Add a new standing instruction to the active execution context.
+*
+* @remarks
+* Delegates to `ctx.storeStandingInstruction(content)`. Standing instructions are stored as
+* a `Set` — adding the same content twice is a no-op at the local level, though the
+* consumer's persistence callback may interpret it differently.
+*/
+var addStandingInstructionTool = new Tool({
+	name: "add_standing_instruction",
+	description: "Add a new standing instruction. Returns the stored content. Adding an identical instruction that already exists is a no-op.",
+	inputSchema: validator.object({ content: validator.string().required().description("The standing-instruction content as a plain string.") }),
+	artifactConstructor: () => SpooledJsonArtifact,
+	handler: async (args, ctx) => {
+		const { content } = args;
+		try {
+			await ctx.storeStandingInstruction(content);
+			return JSON.stringify({
+				ok: true,
+				content
+			}, null, 2);
+		} catch (err) {
+			return `Error: ${isError(err) ? err.message : String(err)}`;
+		}
+	}
+});
+/**
+* Remove an existing standing instruction by its content string.
+*
+* @remarks
+* Delegates to `ctx.deleteStandingInstruction(content)`. Idempotent — succeeds even when
+* no matching instruction is currently present.
+*/
+var removeStandingInstructionTool = new Tool({
+	name: "remove_standing_instruction",
+	description: "Remove a standing instruction by its exact content string. Idempotent — succeeds even when no match is present.",
+	inputSchema: validator.object({ content: validator.string().required().description("The exact content string of the instruction to remove.") }),
+	artifactConstructor: () => SpooledJsonArtifact,
+	handler: async (args, ctx) => {
+		const { content } = args;
+		try {
+			await ctx.deleteStandingInstruction(content);
+			return JSON.stringify({
+				ok: true,
+				content
+			}, null, 2);
+		} catch (err) {
+			return `Error: ${isError(err) ? err.message : String(err)}`;
+		}
+	}
+});
+/**
+* Convenience tuple of every standing-instruction tool. Spread into a {@link @nhtio/adk!ToolRegistry}
+* to register the entire category at once.
+*/
+var standingInstructionTools = [
+	listStandingInstructionsTool,
+	addStandingInstructionTool,
+	removeStandingInstructionTool
+];
+//#endregion
+export { addStandingInstructionTool, listStandingInstructionsTool, removeStandingInstructionTool, standingInstructionTools };
+
+//# sourceMappingURL=standing_instructions.mjs.map

package/batteries/tools/standing_instructions.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"standing_instructions.mjs","names":[],"sources":["../../../src/batteries/tools/standing_instructions/index.ts"],"sourcesContent":["/**\n * Pre-constructed CRUD tools for model-visible standing instruction management.\n *\n * @module @nhtio/adk/batteries/tools/standing_instructions\n *\n * @remarks\n * Pre-constructed CRUD tools that expose the ADK's standing-instruction surface to the\n * model. Each tool delegates to the corresponding callback on the active\n * {@link @nhtio/adk!DispatchContext} (`standingInstructions` getter, `storeStandingInstruction`,\n * `deleteStandingInstruction`) — the persistence layer is whatever the consumer wired into\n * the runner.\n *\n * Standing instructions are stored as a {@link Set} of {@link @nhtio/adk!Tokenizable} values keyed by\n * identity, not by an `id` field — there is no separate \"update by id\" semantics. The tools\n * therefore expose only `list` / `add` / `remove`. To replace an existing instruction the\n * model should `remove` the old value and `add` the new one (the ADK's persistence layer\n * is free to interpret that pair as an update if appropriate).\n *\n * Output is JSON for every tool so consumers can parse the result without re-tokenising —\n * the artifact constructor is set to {@link @nhtio/adk!SpooledJsonArtifact}.\n *\n * Tools:\n * - {@link listStandingInstructionsTool} — read-only list of every standing instruction\n *   currently held by the context (after refreshing from the persistence layer).\n * - {@link addStandingInstructionTool} — add a new standing instruction.\n * - {@link removeStandingInstructionTool} — remove a standing instruction by its content\n *   (exact string match).\n */\n\nimport { isError } from '@nhtio/adk/guards'\nimport { validator } from '@nhtio/validation'\nimport { SpooledJsonArtifact, Tool } from '@nhtio/adk/common'\n\n/**\n * List every standing instruction currently held by the active execution context.\n *\n * @remarks\n * Calls `ctx.refreshStandingInstructions()` to ensure the local Set is in sync with the\n * persistence layer, then serialises the resulting strings to a JSON array. The list is\n * stringly-keyed; the same content string serves as the identifier for subsequent removes.\n */\nexport const listStandingInstructionsTool = new Tool({\n  name: 'list_standing_instructions',\n  description:\n    'List every standing instruction currently held by the agent. Returns a JSON array of strings. To replace an instruction, remove the old string and add a new one.',\n  inputSchema: validator.object({}),\n  artifactConstructor: () => SpooledJsonArtifact,\n  handler: async (_args, ctx) => {\n    try {\n      const refreshed = await ctx.refreshStandingInstructions()\n      const items = refreshed.map((v) => (typeof v === 'string' ? v : v.toString()))\n      return JSON.stringify(items, null, 2)\n    } catch (err) {\n      return `Error: ${isError(err) ? err.message : String(err)}`\n    }\n  },\n})\n\n/**\n * Add a new standing instruction to the active execution context.\n *\n * @remarks\n * Delegates to `ctx.storeStandingInstruction(content)`. Standing instructions are stored as\n * a `Set` — adding the same content twice is a no-op at the local level, though the\n * consumer's persistence callback may interpret it differently.\n */\nexport const addStandingInstructionTool = new Tool({\n  name: 'add_standing_instruction',\n  description:\n    'Add a new standing instruction. Returns the stored content. Adding an identical instruction that already exists is a no-op.',\n  inputSchema: validator.object({\n    content: validator\n      .string()\n      .required()\n      .description('The standing-instruction content as a plain string.'),\n  }),\n  artifactConstructor: () => SpooledJsonArtifact,\n  handler: async (args, ctx) => {\n    const { content } = args as { content: string }\n    try {\n      await ctx.storeStandingInstruction(content)\n      return JSON.stringify({ ok: true, content }, null, 2)\n    } catch (err) {\n      return `Error: ${isError(err) ? err.message : String(err)}`\n    }\n  },\n})\n\n/**\n * Remove an existing standing instruction by its content string.\n *\n * @remarks\n * Delegates to `ctx.deleteStandingInstruction(content)`. Idempotent — succeeds even when\n * no matching instruction is currently present.\n */\nexport const removeStandingInstructionTool = new Tool({\n  name: 'remove_standing_instruction',\n  description:\n    'Remove a standing instruction by its exact content string. Idempotent — succeeds even when no match is present.',\n  inputSchema: validator.object({\n    content: validator\n      .string()\n      .required()\n      .description('The exact content string of the instruction to remove.'),\n  }),\n  artifactConstructor: () => SpooledJsonArtifact,\n  handler: async (args, ctx) => {\n    const { content } = args as { content: string }\n    try {\n      await ctx.deleteStandingInstruction(content)\n      return JSON.stringify({ ok: true, content }, null, 2)\n    } catch (err) {\n      return `Error: ${isError(err) ? err.message : String(err)}`\n    }\n  },\n})\n\n/**\n * Convenience tuple of every standing-instruction tool. Spread into a {@link @nhtio/adk!ToolRegistry}\n * to register the entire category at once.\n */\nexport const standingInstructionTools = [\n  listStandingInstructionsTool,\n  addStandingInstructionTool,\n  removeStandingInstructionTool,\n] as const\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyCA,IAAa,+BAA+B,IAAI,KAAK;CACnD,MAAM;CACN,aACE;CACF,aAAa,UAAU,OAAO,CAAC,CAAC;CAChC,2BAA2B;CAC3B,SAAS,OAAO,OAAO,QAAQ;EAC7B,IAAI;GAEF,MAAM,SAAQ,MADU,IAAI,4BAA4B,GAChC,KAAK,MAAO,OAAO,MAAM,WAAW,IAAI,EAAE,SAAS,CAAE;GAC7E,OAAO,KAAK,UAAU,OAAO,MAAM,CAAC;EACtC,SAAS,KAAK;GACZ,OAAO,UAAU,QAAQ,GAAG,IAAI,IAAI,UAAU,OAAO,GAAG;EAC1D;CACF;AACF,CAAC;;;;;;;;;AAUD,IAAa,6BAA6B,IAAI,KAAK;CACjD,MAAM;CACN,aACE;CACF,aAAa,UAAU,OAAO,EAC5B,SAAS,UACN,OAAO,EACP,SAAS,EACT,YAAY,qDAAqD,EACtE,CAAC;CACD,2BAA2B;CAC3B,SAAS,OAAO,MAAM,QAAQ;EAC5B,MAAM,EAAE,YAAY;EACpB,IAAI;GACF,MAAM,IAAI,yBAAyB,OAAO;GAC1C,OAAO,KAAK,UAAU;IAAE,IAAI;IAAM;GAAQ,GAAG,MAAM,CAAC;EACtD,SAAS,KAAK;GACZ,OAAO,UAAU,QAAQ,GAAG,IAAI,IAAI,UAAU,OAAO,GAAG;EAC1D;CACF;AACF,CAAC;;;;;;;;AASD,IAAa,gCAAgC,IAAI,KAAK;CACpD,MAAM;CACN,aACE;CACF,aAAa,UAAU,OAAO,EAC5B,SAAS,UACN,OAAO,EACP,SAAS,EACT,YAAY,wDAAwD,EACzE,CAAC;CACD,2BAA2B;CAC3B,SAAS,OAAO,MAAM,QAAQ;EAC5B,MAAM,EAAE,YAAY;EACpB,IAAI;GACF,MAAM,IAAI,0BAA0B,OAAO;GAC3C,OAAO,KAAK,UAAU;IAAE,IAAI;IAAM;GAAQ,GAAG,MAAM,CAAC;EACtD,SAAS,KAAK;GACZ,OAAO,UAAU,QAAQ,GAAG,IAAI,IAAI,UAAU,OAAO,GAAG;EAC1D;CACF;AACF,CAAC;;;;;AAMD,IAAa,2BAA2B;CACtC;CACA;CACA;AACF"}

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

@@ -0,0 +1,46 @@
+/**
+ * Pre-constructed tools for descriptive statistics, correlation, quantiles, and numeric summaries.
+ *
+ * @module @nhtio/adk/batteries/tools/statistics
+ *
+ * @remarks
+ * Pre-constructed bundled tools for the `statistics` category. Import individually, the whole
+ * category, or import every tool via `@nhtio/adk/batteries`.
+ */
+import { Tool, SpooledJsonArtifact } from "../../../common";
+/**
+ * Compute descriptive statistics for a JSON array of numbers.
+ *
+ * @remarks
+ * Returns count, sum, min/max/range, mean, median, mode, variance, standard deviation,
+ * quartiles (Q1/Q2/Q3), IQR, and key percentiles (P10/P90/P95/P99) as a pretty-printed JSON
+ * object. Non-numeric and non-finite entries are silently filtered.
+ */
+export declare const statsDescribeTool: Tool<SpooledJsonArtifact<unknown>>;
+/**
+ * Compute the Pearson correlation coefficient between two numeric arrays.
+ *
+ * @remarks
+ * Returns `r`, `r²` (as a percentage of explained variance), and a plain-English interpretation
+ * of strength and direction. Arrays must be the same length and contain at least two points.
+ */
+export declare const statsCorrelateTool: Tool<import("../../../common").SpooledArtifact>;
+/**
+ * Transform a numeric array — normalise, smooth, rank, or detect outliers.
+ *
+ * @remarks
+ * Supported operations: `normalize_min_max`, `normalize_z_score`, `normalize_percent_of_sum`,
+ * `running_total`, `rolling_avg`, `pct_change`, `rank`, `outliers_iqr`, `outliers_zscore`. Most
+ * operations return a JSON array of transformed values; outlier operations return a
+ * human-readable report.
+ */
+export declare const statsTransformTool: Tool<import("../../../common").SpooledArtifact>;
+/**
+ * Bin a numeric array into equal-width histogram buckets.
+ *
+ * @remarks
+ * Output is a text histogram showing each bin's range, count, percentage of total, and a bar
+ * chart. The last bin is inclusive on both ends; preceding bins are half-open. `bins` is clamped
+ * to `[2, 100]`.
+ */
+export declare const statsHistogramTool: Tool<import("../../../common").SpooledArtifact>;