Tools batteries

Date math, CSV parsing, and memory CRUD are already covered. Import the battery and move on.

import { calculateTool, memoryTools } from '@nhtio/adk/batteries'

ADK ships a catalogue of pre-constructed Tool instances organized into categories. No factory calls, no configuration, and no hand-waving setup. You import them, register them, and get back to your actual business logic.

Import Paths

Import battery tools from the batteries barrel:

import { calculateTool, parseCsvTool, getCurrentTimeTool } from '@nhtio/adk/batteries'

You can still keep your own imports grouped by category for readability:

import {
  calculateTool,
  evaluateKatexTool,
  parseCsvTool,
  parseYamlTool,
} from '@nhtio/adk/batteries'

Use the exported tool instances directly.

Wiring into the Runner

Every battery tool is a fully constructed Tool instance. Pass them directly to the TurnRunner constructor. The storage callback spread below is a local placeholder; the ADK does not ship a drop-in no-op storage adapter, so your application must provide every required TurnRunner storage callback:

import { TurnRunner } from '@nhtio/adk'
import { calculateTool, formatTableTool, getCurrentTimeTool } from '@nhtio/adk/batteries'

const storageCallbacks = {
  // Provide every required TurnRunner storage callback here.
}

const runner = new TurnRunner({
  ...storageCallbacks,
  executorCallback: adapter.executor(),
  tools: [calculateTool, formatTableTool, getCurrentTimeTool],
})

adapter here refers to an LLM battery instance. The executor does not call ctx.ack() by default — the implementor owns turn completion. Pass autoAck: true when constructing the adapter to restore single-shot behavior; see LLM batteries.

Compose battery tools with custom tools by passing a flat array:

import { TurnRunner } from '@nhtio/adk'
import { parseCsvTool } from '@nhtio/adk/batteries'
import { getWeather, createTicket } from './tools'

const storageCallbacks = {
  // Provide every required TurnRunner storage callback here.
}

const runner = new TurnRunner({
  ...storageCallbacks,
  executorCallback: adapter.executor(),
  tools: [parseCsvTool, getWeather, createTicket],
})

If you need explicit control over collisions or are managing dynamic tools, construct a ToolRegistry directly:

import { ToolRegistry } from '@nhtio/adk'
import { memoryTools } from '@nhtio/adk/batteries/tools/memory'

// Do NOT look for ToolRegistry.fromTools — it does not exist. Use the constructor.
const baseRegistry = new ToolRegistry([...memoryTools, ...myCustomTools])

Trust & Artifact Constructors

By design, all battery tools default to trusted: false. Tool executions are untrusted inputs, not developer-authored source code. Their output is routed through the untrusted content envelope automatically.

Furthermore, these tools do not share a single uniform artifact constructor. Many omit artifactConstructor entirely (falling back to the default SpooledArtifact), while those processing structured outputs explicitly set SpooledJsonArtifact. Their internal artifact types are not a guessing game; use the tools as exported.

ADK-Native Batteries

These tools hook directly into the active DispatchContext. They delegate execution to the exact storage callbacks you wired into your runner. They are the most valuable batteries in the toolkit because they allow the model to manage its own persistent state.

ADK-Native Tools (Memory, Retrievables, Standing Instructions)

Memory Tools

Category: memory

Allows the model to run CRUD operations on its memory bank.

• listMemoriesTool — Lists memories returned by ctx.fetchMemories().
• storeMemoryTool — Creates a new memory via ctx.storeMemory().
• updateMemoryTool — Replaces an existing memory by ID via ctx.mutateMemory().
• deleteMemoryTool — Removes a memory by ID via ctx.deleteMemory().
• memoryTools — A pre-assembled array of all four memory tools.

Peer dependencies: luxon, uuid

import { TurnRunner } from '@nhtio/adk'
import { calculateTool } from '@nhtio/adk/batteries'
import { memoryTools } from '@nhtio/adk/batteries/tools/memory'

const otherTools = [calculateTool]

const storageCallbacks = {
  // Provide every required TurnRunner storage callback here.
}

const runner = new TurnRunner({
  ...storageCallbacks,
  executorCallback: adapter.executor(),
  tools: [...memoryTools, ...otherTools],
})

Retrievable Tools

Category: retrievables

Allows the model to control which document fragments or chunks are pinned to the context.

• listRetrievablesTool — Lists retrievables returned by ctx.fetchRetrievables().
• storeRetrievableTool — Creates a retrievable via ctx.storeRetrievable().
• updateRetrievableTool — Mutates a pinned retrievable.
• deleteRetrievableTool — Removes a pinned retrievable.
• retrievableTools — A pre-assembled array of all four retrievable tools.

Peer dependencies: luxon, uuid

Standing Instructions Tools

Category: standing_instructions

Allows the model to inspect and update its own operational rules. There is no StandingInstruction class; instructions are stored and managed as string | Tokenizable values.

• listStandingInstructionsTool — Lists active standing instructions.
• addStandingInstructionTool — Adds a new standing instruction.
• removeStandingInstructionTool — Removes a standing instruction.
• standingInstructionTools — A pre-assembled array of all three standing instruction tools.

Utility Tool Batteries

Below is the breakdown of utility tools shipped with the ADK. They are grouped into logical domains. If a category lists peer dependencies, you must install those packages yourself.

Numeric Tools

Mathematics

Category: math

• calculateTool — Evaluates a mathematical expression using a sandboxed subset of mathjs.

  MathJS Sandbox Restrictions

  To prevent remote execution and environment pollution, the sandbox explicitly blocks dangerous mathjs capabilities, including import, createUnit, simplify, derivative, and compile. Refer to the source code for the full blocked list.

• evaluateKatexTool — Translates and evaluates a LaTeX/KaTeX math expression.

Peer dependency: mathjs

Statistics

Category: statistics

• statsDescribeTool — Computes descriptive statistics (mean, median, mode, standard deviation, variance, min, max, percentiles) over a numeric array.
• statsCorrelateTool — Computes the Pearson correlation coefficient between two numeric arrays.
• statsTransformTool — Applies numeric transformations such as min-max normalization, z-score normalization, percent-of-sum normalization, running totals, rolling averages, percent change, ranking, and outlier detection.
• statsHistogramTool — Bins a numeric array into a histogram dataset.

Peer dependency: simple-statistics

Unit Conversion

Category: unit_conversion

• convertUnitTool — Converts physical units across dimensions (length, mass, volume, temperature, speed, etc.). :::

Data Tools

Data Structures

Category: data_structure

• jsonTransformTool — Applies a JSONPath or jq-style transformation to a JSON value.
• setOperationsTool — Computes union, intersection, difference, and symmetric difference over array sets.

Structured Data

Category: structured_data

• formatTableTool — Formats a row array as a Markdown, CSV, or TSV table.
• jsonFormatTool — Pretty-prints or minifies a JSON value.
• validateFormatTool — Validates a string against known formats such as email, UUID, ISO date, hex color, semver, and related common scalar formats.

Formatting

Category: formatting

• formatNumberTool — Formats a number with locale-aware separators, decimal places, and units.
• formatListTool — Formats an array as a natural-language list (e.g., "a, b, and c").

Text Tools

String Processing

Category: string_processing

• stringTransformTool — Converts strings between case styles such as camel_case, snake_case, pascal_case, kebab_case, constant_case, and titlecase.
• stringExtractTool — Extracts substrings using regular expressions or delimiter patterns.

Peer dependency: case-anything

Text Analysis

Category: text_analysis

• textAnalyzeTool — Counts words, sentences, characters, paragraphs, and estimates reading times.
• textLinesTool — Splits text into lines, filters blank lines, and deduplicates rows.

Text Comparison

Category: text_comparison

• textDiffTool — Produces a unified diff between two strings.
• stringSimilarityTool — Computes edit distance and similarity scores between two strings.

Peer dependencies: diff, fastest-levenshtein

Encoding & Escaping

Category: encoding

• encodeTextTool — Encodes and decodes between Base64, Base64URL, hex, URL encoding, and UTF-8.
• textEscapeTool — Escapes and unescapes HTML, XML, JSON strings, and RegExp special characters.
• unicodeNormalizeTool — Normalizes a string to NFC, NFD, NFKC, or NFKD forms.

Parsing

Category: parsing

• parseCsvTool — Parses a CSV string into an array of rows. Supports custom delimiters and header detection.
• parseYamlTool — Parses a YAML string into a JSON-serializable value.
• parseKvTool — Parses key=value or KEY: value pairs into an object.
• detectDelimiterTool — Detects the likely delimiter of a structured text file.

Peer dependencies: js-yaml, papaparse

Time Tools

DateTime Math

Category: datetime_math

• dateAddTool — Adds or subtracts a duration from a date.
• dateDiffTool — Computes the duration between two dates.
• durationFormatTool — Formats a duration in human-readable form.

Peer dependency: luxon

DateTime Extended

Category: datetime_extended

• dateNthWeekdayTool — Finds the Nth weekday in a month (e.g., "third Thursday of November").
• dateCalendarInfoTool — Returns calendar metadata for a date, including week number, quarter, and day of the year.
• dateParseTool — Parses a natural-language date expression (e.g., "next Monday", "in two weeks").
• datePeriodTool — Computes the start and end of a named period (e.g., "this quarter", "last month").
• dateBusinessDaysTool — Counts business days between two dates, optionally excluding specified holidays.

Peer dependencies: chrono-node, luxon

Time

Category: time

• getCurrentTimeTool — Returns the current date and time in a specified timezone.
• convertTimeTool — Converts a datetime value from one timezone to another.

Peer dependency: luxon

Miscellaneous Tools

Color

Category: color

• colorContrastTool — Computes the WCAG contrast ratio between two colors.
• colorSchemeTool — Generates complementary, analogous, or triadic color schemes.
• colorAdjustTool — Lightens or darkens a color by HSL lightness.

Comparison

Category: comparison

• compareValuesTool — Performs a deep comparison of two values and returns relative order.
• compareRecordsTool — Diffs two objects and returns lists of added, removed, and modified keys.

Geospatial Basics

Category: geo_basics

• geoDistanceTool — Computes the great-circle distance between two latitude/longitude points.
• geoWithinRadiusTool — Checks whether a point lies within a radius of another point.
• geoBboxContainsTool — Checks whether a coordinate point lies within a specified bounding box.

Peer Dependencies

You only pay for peer dependencies if you import the battery category that requires them. If you attempt to use a tool without its peer dependency installed, your runtime will crash with a module resolution error. Install what you import; Node's resolver is not a charity.

Peer dependency	Required Category
mathjs	math
simple-statistics	statistics
js-yaml	parsing
papaparse	parsing
case-anything	string_processing
diff	text_comparison
fastest-levenshtein	text_comparison
chrono-node	datetime_extended
luxon	datetime_math, datetime_extended, time, memory, retrievables
uuid	memory, retrievables

Any category omitted from this table has zero external dependencies beyond @nhtio/adk itself.