Package com.tnsai.tools.utility

Class UtilityTools

java.lang.Object

com.tnsai.tools.utility.UtilityTools

public class UtilityTools
extends Object

Function-shape pure-JDK utility tools — replaces the legacy CalculatorTool, HashingTool, and DateTimeTool (#188).

Five typed @Tool methods, all dependency-free (no external API keys, no extra Maven dependencies — pure JDK + standard java.time + java.security):

Method	Purpose
calculator(java.lang.String)	Evaluate an arithmetic expression
hash(java.lang.String, java.lang.String)	MD5/SHA-1/SHA-256/SHA-512 hex digest
datetimeNow(java.lang.String)	Current ISO-8601 timestamp in a timezone
datetimeDiff(java.lang.String, java.lang.String, java.lang.String)	Difference between two timestamps in a unit
datetimeAdd(java.lang.String, long, java.lang.String)	Add an amount of a unit to a timestamp

QR-code generation/reading and Google Translate are out of this POJO — they live in EncodingTools (next batch) because they pull external deps (zxing + Google Cloud Translation API key).

Since:

0.5.7 (Phase 2 batch 8 — built-in tool migration to function shape, see #188)

Constructor Summary

Constructors

Constructor	Description
UtilityTools()

Method Summary

Modifier and Type	Method	Description
String	calculator(String expression)
String	datetimeAdd(String timestamp, long amount, String unit)
long	datetimeDiff(String from, String to, String unit)
String	datetimeNow(String timezone)
String	hash(String text, String algorithm)

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

UtilityTools

public UtilityTools()

Method Details

calculator

@Tool(name="calculator",
      description="Evaluate an arithmetic expression. Supports +, -, *, /, ^ (power), parentheses, and the unary functions sqrt, sin, cos, tan (trig in degrees). Returns the numeric result as a string \u2014 integer when whole, decimal otherwise. Use this whenever an LLM needs to do exact arithmetic instead of guessing.",
      keywords={"math","arithmetic","calculate","compute","expression"},
      idempotent=true)
public String calculator(@ToolParam(description="Arithmetic expression, e.g. \"(2 + 3) * 5\", \"sqrt(2)\", \"sin(30)\"")
 String expression)

hash

@Tool(name="hash",
      description="Compute the cryptographic hex digest of a UTF-8 text using {algorithm}. Supported algorithms: MD5, SHA-1, SHA-256 (default), SHA-512. Common aliases (\"sha256\", \"sha512\", \"sha1\") are accepted. Returns the lower-case hex string.",
      keywords={"hash","digest","md5","sha","sha256","checksum","crypto"},
      idempotent=true)
public String hash(@ToolParam(description="UTF-8 text to hash (empty string is accepted; null is rejected)")
 String text,
 @ToolParam(description="Algorithm name: MD5, SHA-1 (or \"sha1\"), SHA-256 (default; or \"sha256\"), SHA-512 (or \"sha512\")",required=false,defaultValue="SHA-256")
 String algorithm)

datetimeNow

@Tool(name="datetime_now",
      description="Get the current date+time as an ISO-8601 string in the given {timezone}. Default timezone is UTC. Examples: \"Europe/Istanbul\", \"America/New_York\", \"UTC\". Returns a string like \"2026-04-28T15:30:45+03:00\".",
      keywords={"datetime","date","time","now","timezone","iso8601"},
      idempotent=false)
public String datetimeNow(@ToolParam(description="IANA timezone id (e.g. \"Europe/Istanbul\", \"America/New_York\", \"UTC\")",required=false,defaultValue="UTC")
 String timezone)

datetimeDiff

@Tool(name="datetime_diff",
      description="Calculate the difference between two ISO-8601 timestamps in the requested {unit}. Supported units: seconds, minutes, hours, days, weeks. Result is signed: positive when {to} is after {from}, negative when before. Returns a long.",
      keywords={"datetime","diff","difference","duration"},
      idempotent=true)
public long datetimeDiff(@ToolParam(description="Earlier (or later) ISO-8601 timestamp")
 String from,
 @ToolParam(description="Later (or earlier) ISO-8601 timestamp")
 String to,
 @ToolParam(description="Unit: seconds, minutes, hours, days, weeks (default days)",required=false,defaultValue="days")
 String unit)

datetimeAdd

@Tool(name="datetime_add",
      description="Add (or subtract) {amount} units of {unit} to an ISO-8601 {timestamp}. Negative amounts subtract. Supported units: seconds, minutes, hours, days, weeks. Returns the resulting ISO-8601 timestamp string.",
      keywords={"datetime","add","subtract","shift","duration"},
      idempotent=true)
public String datetimeAdd(@ToolParam(description="ISO-8601 timestamp (e.g. \"2026-04-28T12:00:00Z\")")
 String timestamp,
 @ToolParam(description="Amount to add (negative subtracts)")
 long amount,
 @ToolParam(description="Unit: seconds, minutes, hours, days, weeks")
 String unit)