Convert Unit Tool

Fast unit conversion tool with support for multiple unit categories. This tool provides accurate unit conversions across different measurement systems and integrates seamlessly with AI agents.

Features

• Multi-Category Support: Length, mass, volume, temperature, time, data, area, speed, and more
• Natural Language Input: Supports expressions like "5 meters to feet", "32°F to celsius"
• Structured Input: Direct value and unit specification for programmatic use
• Type Safety: Full TypeScript support with proper type definitions
• Performance: Fast conversions using the Convert library
• Error Handling: Comprehensive validation and helpful error messages
• Precision Control: Configurable decimal precision (1-15 digits)

Installation

npm install
npm run build

Usage

Basic Conversions

import { convertUnitToolDefinition } from 'convert-unit-tool';

// Length conversion
const result = await convertUnitTool({
  value: 5,
  fromUnit: "meters",
  toUnit: "feet"
});
// Result: 16.404 feet

// Temperature conversion
const temp = await convertUnitTool({
  value: 32,
  fromUnit: "fahrenheit",
  toUnit: "celsius"
});
// Result: 0 celsius

Natural Language Expressions

// Natural language input
const result = await convertUnitTool({
  expression: "5 meters to feet"
});
// Result: 16.404 feet

const distance = await convertUnitTool({
  expression: "100 km to miles"
});
// Result: 62.137 miles

With Precision Control

const precise = await convertUnitTool({
  value: 1,
  fromUnit: "meters",
  toUnit: "feet",
  precision: 3
});
// Result: 3.28 feet (limited to 3 significant digits)

Supported Unit Categories

• Length: meters, feet, inches, kilometers, miles, centimeters, millimeters
• Mass/Weight: grams, kilograms, pounds, ounces
• Volume: liters, gallons, milliliters, cubic meters, fluid ounces
• Temperature: celsius, fahrenheit, kelvin
• Time: seconds, minutes, hours, days, weeks
• Data: bytes, kilobytes, megabytes, gigabytes (decimal, 1000-based)
• Area: square meters, square feet, acres, hectares
• Speed: meters per second, kilometers per hour, miles per hour

Unit Aliases

The tool supports common unit abbreviations:

• ft → feet
• in → inches
• kg → kilograms
• lb, lbs → pounds
• c → celsius
• f → fahrenheit
• hr, hrs → hours
• min → minutes

Error Handling

The tool provides comprehensive error handling with helpful suggestions:

const result = await convertUnitTool({
  value: 5,
  fromUnit: "invalid",
  toUnit: "feet"
});

if (result.error) {
  console.log(result.message); // "Unit conversion failed: ..."
  console.log(result.details); // Helpful suggestions
}

Integration with Math Tool

The convert-unit tool works seamlessly with the math-tool for complex calculations:

// Step 1: Convert units
const lengthInFeet = await convertUnitTool({
  value: 5,
  fromUnit: "meters",
  toUnit: "feet"
});

// Step 2: Calculate with converted values
const hypotenuse = await mathTool("sqrt(a^2 + b^2)", {
  a: lengthInFeet.result,
  b: 10
});

Testing

Run the comprehensive test suite:

npm run build
node tests/test.js

The test suite covers:

• Basic unit conversions across all categories
• Natural language expression parsing
• Unit aliases and normalization
• Precision control
• Error cases and validation
• Edge cases (zero, negative, large numbers)

Development

Building

npm run build

Development Mode

npm run dev

This watches for file changes and automatically rebuilds the TypeScript code.

Notes

• Data Units: The Convert library uses decimal prefixes (1 GB = 1000 MB), not binary (1024 MB)
• Floating Point: Small precision errors may occur due to floating-point arithmetic
• Temperature: Absolute temperature conversions (not relative temperature differences)
• Performance: Optimized for high-frequency conversions with minimal overhead

Dependencies

• convert: Modern, lightweight unit conversion library
• agent-core: Core AI agent functionality
• ai: Vercel AI SDK for tool integration
• zod: Runtime type validation

License

ISC