toolregistry.hub package

ToolRegistry Hub module providing commonly used tools.

This module serves as a central hub for various utility tools including: - Calculator: Basic arithmetic operations - FileSystem: File system operations - FileOps: File manipulation functions - UnitConverter: Unit conversion functions

Example

>>> from toolregistry.hub import Calculator, FileSystem, FileOps
>>> calc = Calculator()
>>> result = calc.add(1, 2)
>>> fs = FileSystem()
>>> exists = fs.exists('/path/to/file')
>>> ops = FileOps()
>>> ops.replace_lines('file.txt', 5, 'new content')
class toolregistry.hub.Calculator[source]

Bases: object

Performs mathematical calculations.

This class provides a unified interface for a wide range of mathematical operations, including basic arithmetic, scientific functions, statistical calculations, financial computations, random number generation, and expression evaluation.

Constants()

pi, e, tau, inf, nan

Basic arithmetic

add, subtract, multiply, divide, mod

Power and roots

power, sqrt, cbrt, isqrt

Distance and norm

dist, hypot

Trigonometric functions

sin, cos, tan, asin, acos, atan, degrees, radians

Hyperbolic functions

sinh, cosh, tanh, asinh, acosh, atanh

Logarithmic and exponential functions

log, ln, log10, log2, log1p, exp, expm1

Numerical processing

abs, round, floor, ceil, trunc, copysign, frexp, ldexp, modf, remainder, nextafter, ulp, fmod, isclose

Combinatorics()

factorial, gcd, lcm, comb, perm

Special functions

erf, erfc, gamma, lgamma

Numerical validation

isfinite, isinf, isnan

Statistical functions

average, median, mode, standard_deviation, min, max, sum, prod, fsum

Financial calculations

simple_interest, compound_interest

Random number generation

random, randint

Expression evaluation

evaluate

static pi() float[source]

Returns the mathematical constant π.

static e() float[source]

Returns the mathematical constant e.

static tau() float[source]

Returns the mathematical constant tau (2π).

static inf() float[source]

Returns positive infinity.

static nan() float[source]

Returns NaN (Not a Number).

static add(a: float, b: float) float[source]

Adds two numbers.

static subtract(a: float, b: float) float[source]

Subtracts two numbers.

static multiply(a: float, b: float) float[source]

Multiplies two numbers.

static divide(a: float, b: float) float[source]

Divides two numbers.

static mod(a: float, b: float) float[source]

Calculates a modulo b.

static power(base: float, exponent: float) float[source]

Raises base to exponent power.

static sqrt(x: float) float[source]

Calculates square root of a number.

static cbrt(x: float) float[source]

Calculates cube root of a number.

static isqrt(n: int) int[source]

Calculates integer square root of non-negative integer n.

static dist(p: List[float], q: List[float]) float[source]

Calculates Euclidean distance between two points.

static hypot(*coordinates: float) float[source]

Calculates Euclidean norm (sqrt(sum(x^2))).

static sin(x: float) float[source]

Calculates sine of x (in radians).

static cos(x: float) float[source]

Calculates cosine of x (in radians).

static tan(x: float) float[source]

Calculates tangent of x (in radians).

static asin(x: float) float[source]

Calculates arcsine of x (in radians).

static acos(x: float) float[source]

Calculates arccosine of x (in radians).

static atan(x: float) float[source]

Calculates arctangent of x (in radians).

static degrees(x: float) float[source]

Converts angle x from radians to degrees.

static radians(x: float) float[source]

Converts angle x from degrees to radians.

static sinh(x: float) float[source]

Calculates the hyperbolic sine of x.

static cosh(x: float) float[source]

Calculates the hyperbolic cosine of x.

static tanh(x: float) float[source]

Calculates the hyperbolic tangent of x.

static asinh(x: float) float[source]

Calculates the inverse hyperbolic sine of x.

static acosh(x: float) float[source]

Calculates the inverse hyperbolic cosine of x. x must be >= 1.

static atanh(x: float) float[source]

Calculates the inverse hyperbolic tangent of x. |x| must be less than 1.

static log(x: float, base: float = 10) float[source]

Calculates logarithm of x with given base.

static ln(x: float) float[source]

Calculates natural (base-e) logarithm of x.

static log10(x: float) float[source]

Calculates base-10 logarithm of x.

static log2(x: float) float[source]

Calculates base-2 logarithm of x.

static log1p(x: float) float[source]

Calculates the natural logarithm of 1+x.

static exp(x: float) float[source]

Calculates the exponential of x (e^x).

static expm1(x: float) float[source]

Calculates e^x - 1 accurately for small x.

static abs(x: float) float[source]

Calculates absolute value of x.

static round(x: float, digits: int = 0) float[source]

Rounds x to given number of decimal digits.

static floor(x: float) int[source]

Rounds x down to nearest integer.

static ceil(x: float) int[source]

Rounds x up to nearest integer.

static trunc(x: float) int[source]

Truncates x by removing the fractional part.

static copysign(a: float, b: float) float[source]

Returns a float with the magnitude of a but the sign of b.

static frexp(x: float)[source]

Returns the mantissa and exponent of x as the pair (m, e).

static ldexp(x: float, i: int) float[source]

Returns x * (2**i) computed exactly.

static modf(x: float)[source]

Returns the fractional and integer parts of x.

static remainder(x: float, y: float) float[source]

Returns IEEE 754-style remainder of x/y.

static nextafter(x: float, y: float) float[source]

Returns next floating-point value after x towards y.

static ulp(x: float) float[source]

Returns the value of the least significant bit of x.

static fmod(x: float, y: float) float[source]

Returns floating-point remainder of x/y.

static isclose(a: float, b: float, rel_tol: float = 1e-09, abs_tol: float = 0.0) bool[source]

Determines whether two floats are close in value.

static factorial(n: int) int[source]

Calculates factorial of n.

static gcd(a: int, b: int) int[source]

Calculates greatest common divisor of a and b.

static lcm(a: int, b: int) int[source]

Calculates least common multiple of a and b.

static comb(n: int, k: int) int[source]

Calculates the number of combinations (n choose k).

static perm(n: int, k: int) int[source]

Calculates the number of permutations of n items taken k at a time.

static erf(x: float) float[source]

Calculates the error function of x.

static erfc(x: float) float[source]

Calculates the complementary error function of x.

static gamma(x: float) float[source]

Calculates the Gamma function of x.

static lgamma(x: float) float[source]

Calculates the natural logarithm of the absolute value of the Gamma function of x.

static isfinite(x: float) bool[source]

Checks if x is finite.

static isinf(x: float) bool[source]

Checks if x is infinite.

static isnan(x: float) bool[source]

Checks if x is NaN.

static average(numbers: List[float]) float[source]

Calculates arithmetic mean of numbers.

static median(numbers: List[float]) float[source]

Calculates median of numbers.

static mode(numbers: List[float]) List[float][source]

Finds mode(s) of numbers.

static standard_deviation(numbers: List[float]) float[source]

Calculates population standard deviation of numbers.

static min(numbers: List[float]) float[source]

Finds the minimum value in a list of numbers.

static max(numbers: List[float]) float[source]

Finds the maximum value in a list of numbers.

static sum(numbers: List[float]) float[source]

Calculates the sum of a list of numbers.

static prod(numbers: List[float]) float[source]

Calculates the product of a list of numbers.

static fsum(numbers: List[float]) float[source]

Calculates an accurate floating point sum of numbers.

static simple_interest(principal: float, rate: float, time: float) float[source]

Calculates simple interest.

Parameters:
  • principal (float) – Initial amount

  • rate (float) – Annual interest rate (decimal)

  • time (float) – Time in years

Returns:

Simple interest amount

Return type:

float

static compound_interest(principal: float, rate: float, time: float, periods: int = 1) float[source]

Calculates compound interest.

Parameters:
  • principal (float) – Initial amount

  • rate (float) – Annual interest rate (decimal)

  • time (float) – Time in years

  • periods (int, optional) – Compounding periods per year. Defaults to 1.

Returns:

Final amount after compounding

Return type:

float

static random() float[source]

Generates random float between 0 and 1.

static randint(a: int, b: int) int[source]

Generates random integer between a and b.

static evaluate(expression: str) float | int | bool[source]

Evaluates a mathematical expression using a unified interface.

This method is intended for complex expressions that combine two or more operations. For simple, single-step operations, please directly use the corresponding static method (e.g., add, subtract).

The evaluate method supports the following operations:
  • Constants: pi, e, tau, inf, nan

  • Basic arithmetic: add, subtract, multiply, divide, mod

  • Power and roots: power, sqrt, cbrt, isqrt

  • Distance and norm: dist, hypot

  • Trigonometric functions: sin, cos, tan, asin, acos, atan, degrees, radians

  • Hyperbolic functions: sinh, cosh, tanh, asinh, acosh, atanh

  • Logarithmic and exponential functions: log, ln, log10, log2, log1p, exp, expm1

  • Numerical processing: abs, round, floor, ceil, trunc, copysign, frexp, ldexp, modf, remainder, nextafter, ulp, fmod, isclose

  • Combinatorics: factorial, gcd, lcm, comb, perm

  • Special functions: erf, erfc, gamma, lgamma

  • Numerical validation: isfinite, isinf, isnan

  • Statistical functions: average, median, mode, standard_deviation, min, max, sum, prod, fsum

  • Financial calculations: simple_interest, compound_interest

  • Random number generation: random, randint

The expression should be a valid Python expression utilizing the above functions. For example: “add(2, 3) * power(2, 3) + sqrt(16)”.

Parameters:

expression (str) – Mathematical expression to evaluate.

Returns:

The result of the evaluated expression.

Return type:

Union[float, int, bool]

Raises:

ValueError – If the expression is invalid or its evaluation fails.

class toolregistry.hub.FileSystem[source]

Bases: object

Provides file system operations related to structure, state, and metadata.

exists(path)[source]

Checks if path exists

is_file(path)[source]

Checks if path is a file

is_dir(path)[source]

Checks if path is a directory

list_dir(path)[source]

Lists directory contents

create_file(path)[source]

Creates an empty file or updates timestamp (like touch)

copy(src, dst)[source]

Copies file/directory

move(src, dst)[source]

Moves/renames file/directory

delete(path)[source]

Deletes file/directory

get_size(path)[source]

Gets file/directory size in bytes

get_last_modified_time(path)[source]

Gets file last modified time (Unix timestamp)

join_paths(*paths)[source]

Joins path components

get_absolute_path(path)[source]

Gets absolute path as a string

create_dir(path)[source]

Creates directory

static exists(path: str) bool[source]

Checks if a path exists.

Parameters:

path – The path string to check.

Returns:

True if path exists, False otherwise

static is_file(path: str) bool[source]

Checks if a path points to a file.

Parameters:

path – The path string to check.

Returns:

True if the path points to a file, False otherwise.

static is_dir(path: str) bool[source]

Checks if a path points to a directory.

Parameters:

path – The path string to check.

Returns:

True if the path points to a directory, False otherwise.

static list_dir(path: str, depth: int = 1, show_hidden: bool = False) List[str][source]

Lists contents of a directory up to a specified depth.

Parameters:
  • path – The directory path string to list.

  • depth – Maximum depth to list (default=1). Must be >= 1.

  • show_hidden – If False, filters out hidden files/directories. On Unix-like systems (Linux, macOS), this means names starting with ‘.’. On Windows, this means files/directories with the ‘hidden’ attribute set, as well as names starting with ‘.’. (default is False).

Returns:

List of relative path strings of items in the directory up to the specified depth.

Raises:
  • ValueError – If depth is less than 1.

  • FileNotFoundError – If the path does not exist or is not a directory.

static create_file(path: str) None[source]

Creates an empty file or updates the timestamp if it already exists (like ‘touch’).

Parameters:

path – The file path string to create or update.

static copy(src: str, dst: str) None[source]

Copies a file or directory.

Parameters:
  • src – Source path string.

  • dst – Destination path string.

static move(src: str, dst: str) None[source]

Moves/renames a file or directory.

Parameters:
  • src – Source path string.

  • dst – Destination path string.

static delete(path: str) None[source]

Deletes a file or directory recursively.

Parameters:

path – Path string to delete.

static get_size(path: str) int[source]

Gets file/directory size in bytes (recursive for directories).

Parameters:

path – Path string to check size of.

Returns:

Size in bytes.

Raises:

FileNotFoundError – If the path does not exist.

static get_last_modified_time(path: str) float[source]

Gets the last modified time of a file or directory.

Parameters:

path – Path string to the file or directory.

Returns:

Last modified time as a Unix timestamp (float).

Raises:

FileNotFoundError – If the path does not exist.

static join_paths(*paths: str) str[source]

Joins multiple path components into a normalized string path.

Parameters:

*paths – One or more path component strings.

Returns:

Joined and normalized path string.

static get_absolute_path(path: str) str[source]

Gets the absolute path as a normalized string.

Parameters:

path – Path string to convert.

Returns:

Absolute path string.

static create_dir(path: str, parents: bool = True, exist_ok: bool = True) None[source]

Creates a directory, including parent directories if needed (defaults to True).

Parameters:
  • path – Directory path string to create.

  • parents – Create parent directories if needed (default=True).

  • exist_ok – Don’t raise error if directory exists (default=True).

class toolregistry.hub.FileOps[source]

Bases: object

Core file operations toolkit designed for LLM agent integration.

Handles file reading, atomic writing, appending, searching, and diff-based modifications.

static replace_by_diff(path: str, diff: str) None[source]

Apply unified diff format changes atomically to a file.

Parameters:
  • path – The file path to modify.

  • diff – Unified diff text (must use standard format with —/+++ headers and @@ hunk markers).

Example diff text:

— a/original_file +++ b/modified_file @@ -1,3 +1,3 @@ -line2 +line2 modified

Raises:

ValueError – On invalid diff format or patch failure

static search_files(path: str, regex: str, file_pattern: str = '*') List[dict][source]

Perform regex search across files in a directory, returning matches with context.

Parameters:
  • path – The directory path to search recursively.

  • regex – The regex pattern to search for.

  • file_pattern – Glob pattern to filter files (default=’*’).

Returns:

  • file: file path

  • line_num: line number of match (1-based)

  • line: matched line content

  • context: list of context lines (tuples of line_num, line content)

Return type:

List of dicts with keys

static replace_by_git(path: str, diff: str) None[source]

Apply git conflict style diff atomically to a file, replacing conflicted sections.

Parameters:
  • path – File path to modify.

  • diff – Git conflict style diff text (using <<<<<<< SEARCH, =======, >>>>>>> REPLACE markers).

Example diff text:

<<<<<<< SEARCH line2 ======= line2 modified >>>>>>> REPLACE

Raises:

ValueError – On invalid diff format or patch failure

static read_file(path: str) str[source]

Read text file content.

Parameters:

path – File path to read

Returns:

File content as string

Raises:
  • FileNotFoundError – If path doesn’t exist

  • UnicodeError – On encoding failures

static write_file(path: str, content: str) None[source]

Atomically write content to a text file (overwrite). Creates the file if it doesn’t exist.

Parameters:
  • path – Destination file path

  • content – Content to write

static append_file(path: str, content: str) None[source]

Append content to a text file. Creates the file if it doesn’t exist.

Parameters:
  • path – Destination file path

  • content – Content to append

static make_diff(ours: str, theirs: str) str[source]

Generate unified diff text between two strings.

Parameters:
  • ours – The ‘ours’ version string.

  • theirs – The ‘theirs’ version string.

Note

Intended for comparison/visualization, not direct modification. not for direct text modification tasks.

Returns:

Unified diff text

static make_git_conflict(ours: str, theirs: str) str[source]

Generate git merge conflict marker text between two strings.

Parameters:
  • ours – The ‘ours’ version string.

  • theirs – The ‘theirs’ version string.

Note

Intended for comparison/visualization, not direct modification. not for direct text modification tasks.

Returns:

Text with conflict markers

static validate_path(path: str) Dict[str, bool | str][source]

Validate file path safety (checks for empty paths, dangerous characters).

Parameters:

path – The path string to validate.

Returns:

  • valid (bool): Path safety status

  • message (str): Description if invalid

Return type:

Dictionary with keys

class toolregistry.hub.UnitConverter[source]

Bases: object

Performs unit conversions.

Temperature conversions

celsius_to_fahrenheit, fahrenheit_to_celsius, kelvin_to_celsius, celsius_to_kelvin

Length conversions

meters_to_feet, feet_to_meters, centimeters_to_inches, inches_to_centimeters

Weight conversions

kilograms_to_pounds, pounds_to_kilograms

Time conversions

seconds_to_minutes, minutes_to_seconds

Capacity conversions

liters_to_gallons, gallons_to_liters

Area conversions

square_meters_to_square_feet, square_feet_to_square_meters

Speed conversions

kmh_to_mph, mph_to_kmh

Data storage conversions

bits_to_bytes, bytes_to_kilobytes, kilobytes_to_megabytes

Pressure conversions

pascal_to_bar, bar_to_atm

Power conversions

watts_to_kilowatts, kilowatts_to_horsepower

Energy conversions

joules_to_calories, calories_to_kilowatt_hours

Frequency conversions

hertz_to_kilohertz, kilohertz_to_megahertz

Fuel economy conversions

km_per_liter_to_mpg, mpg_to_km_per_liter

Electrical conversions

ampere_to_milliampere, volt_to_kilovolt, ohm_to_kiloohm

Magnetic conversions

weber_to_tesla, gauss_to_tesla

Radiation conversions

gray_to_sievert

Light intensity conversions

lux_to_lumen, lumen_to_lux

static celsius_to_fahrenheit(celsius: float) float[source]

Convert Celsius to Fahrenheit.

static fahrenheit_to_celsius(fahrenheit: float) float[source]

Convert Fahrenheit to Celsius.

static kelvin_to_celsius(kelvin: float) float[source]

Convert Kelvin to Celsius.

static celsius_to_kelvin(celsius: float) float[source]

Convert Celsius to Kelvin.

static meters_to_feet(meters: float) float[source]

Convert meters to feet.

static feet_to_meters(feet: float) float[source]

Convert feet to meters.

static centimeters_to_inches(cm: float) float[source]

Convert centimeters to inches.

static inches_to_centimeters(inches: float) float[source]

Convert inches to centimeters.

static kilograms_to_pounds(kg: float) float[source]

Convert kilograms to pounds.

static pounds_to_kilograms(lbs: float) float[source]

Convert pounds to kilograms.

static seconds_to_minutes(seconds: float) float[source]

Convert seconds to minutes.

static minutes_to_seconds(minutes: float) float[source]

Convert minutes to seconds.

static liters_to_gallons(liters: float) float[source]

Convert liters to gallons.

static gallons_to_liters(gallons: float) float[source]

Convert gallons to liters.

static square_meters_to_square_feet(sqm: float) float[source]

Convert square meters to square feet.

static square_feet_to_square_meters(sqft: float) float[source]

Convert square feet to square meters.

static kmh_to_mph(kmh: float) float[source]

Convert kilometers per hour to miles per hour.

static mph_to_kmh(mph: float) float[source]

Convert miles per hour to kilometers per hour.

static bits_to_bytes(bits: float) float[source]

Convert bits to bytes.

static bytes_to_kilobytes(bytes: float) float[source]

Convert bytes to kilobytes.

static kilobytes_to_megabytes(kb: float) float[source]

Convert kilobytes to megabytes.

static pascal_to_bar(pascal: float) float[source]

Convert pascal to bar.

static bar_to_atm(bar: float) float[source]

Convert bar to atmosphere.

static watts_to_kilowatts(watts: float) float[source]

Convert watts to kilowatts.

static kilowatts_to_horsepower(kw: float) float[source]

Convert kilowatts to horsepower.

static joules_to_calories(joules: float) float[source]

Convert joules to calories.

static calories_to_kilowatt_hours(calories: float) float[source]

Convert calories to kilowatt hours.

static hertz_to_kilohertz(hz: float) float[source]

Convert hertz to kilohertz.

static kilohertz_to_megahertz(khz: float) float[source]

Convert kilohertz to megahertz.

static km_per_liter_to_mpg(kmpl: float) float[source]

Convert kilometers per liter to miles per gallon.

static mpg_to_km_per_liter(mpg: float) float[source]

Convert miles per gallon to kilometers per liter.

static ampere_to_milliampere(ampere: float) float[source]

Convert ampere to milliampere.

static volt_to_kilovolt(volt: float) float[source]

Convert volt to kilovolt.

static ohm_to_kiloohm(ohm: float) float[source]

Convert ohm to kiloohm.

static weber_to_tesla(weber: float, area: float = 1.0) float[source]

Convert magnetic flux (weber) to magnetic flux density (tesla). Assumes a default area of 1 square meter if not specified.

static gauss_to_tesla(gauss: float) float[source]

Convert gauss to tesla.

static tesla_to_weber(tesla: float, area: float = 1.0) float[source]

Convert magnetic flux density (tesla) to magnetic flux (weber). Assumes a default area of 1 square meter if not specified.

static tesla_to_gauss(tesla: float) float[source]

Convert tesla to gauss.

static gray_to_sievert(gray: float) float[source]

Convert gray to sievert.

static lux_to_lumen(lux: float, area: float) float[source]

Convert lux to lumen given an area in square meters.

static lumen_to_lux(lumen: float, area: float) float[source]

Convert lumen to lux given an area in square meters.

Submodules